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Chapter 1 


System Organization 


tn \ OS-9 is composed of a group of modules, each of which has a spe- 
cific function. The following illustration shows the major mod- 
ules. Actual module names are capitalized. 


I/O System Modules 


) 0S-9 KERNEL 
wu (OS9P1, OS9P2) vous 


| Input Output Manager 
(IOMAN) 


Disk File Pipe File 
Manager Manager 
(RBF) (Pipeman) 


Char. File 
Manager Printer $10 
(SCF) 


ACIAPak ModPak CC3I0 
Driver Driver 


20 o 


CC3Disk 
Disk 
Driver 


CC3Hdisk 
Disk 
Driver 


Ram 
Ram Disk 
Driver 


RBF Device Descriptors Pipe Descr. SCF Device Descriptors 
Vdgint GrfInt Windlnt 
CC310 CC310 CC310 
Interface Interface Interface 


=] | le) 
Desc 
a> Term_Win wll wit} w2 
Desc 


OS-9 COMPONENT MODULE ORGANIZATION 
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Color Computer OS-9 Modules 
IOMAN Input/output management 


INIT System initialization table 

CLOCK Software routine time management 
RBF Random block file management 

SCF Sequential character file management 


PIPEMAN Pipe file management 
CC38DISK Color Computer disk driver 
CC3IO Color Computer input/output driver 


The VDGINT (video display generator) provides both interface 
functions and low-level routines for Color Computer 2 VDG 
compatibility. 


The GRFINT interface provides high-level graphics code interpre- 
tation and interface functions. 


The WINDINT interface contains all the functions of GRFINT, 
along with additional support for Multiview functions. If you are 
using Multiview, exclude GRFINT from the system. 


Both WINDINT and GRFINT use the low-level driver GRFDRV 
to perform the actual drawing on bitmap screens. 


Term__VDG uses CC3IO and VDGINT. TERM__WIWN and all 
window descriptors (W, W1, W2, and so on) use CC3I0O, WIN- 
DINT, GRFINT, and GRFDRV modules. 


Kernel, Clock Module, and INIT 


The system’s first level contains the kernel, clock module, and 
INIT. 


The kernel provides basic system services, such as multitasking 
and memory management. It links all other OS-9 modules into 
the system. 


The clock module is a software handler for the real-time clock 
hardware. 


INIT is an initialization table used by the kernel during system 
startup. This table loads initial tasks and specifies initial table 
sizes and initial system device names. It is loaded into RAM 
(random access memory) by the OS-9 bootstrap module Boot. 
Boot also loads the OS9P2 and INIT modules during system 
startup. 
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There are two ways to run boot: 


e Using the DOS command with Color Disk BASIC, Ver- 
sion 1.1, or later. 


@ Pressing the reset button after OS-9 is running. 


Input/Output Modules 


The remaining modules make up the OS-9 I/O system. They are 
defined briefly here and are discussed in detail in Chapter 4. 


I/O Manager 


The system’s second level (the level below the kernel) contains 
the input/output manager, IOMAN. The I/O manager provides 
common processing for all input/output operations. It is required 
for performing any input/output supported by OS-9. 


File Managers 


The system’s third level contains the file managers. File man- 
agers perform I/O request processing for similar classes of I/O 
devices. There are three file managers: 


RBF manager The random block file manager processes 
all disk I/O operations. 


SCF manager The sequential character file manager han- 
dles all non-disk I/O operations that operate 
one character at a time. These operations 
include terminal and printer I/O. 


PIPEMAN The pipe file manager handles pipes. Pipes 
are memory buffers that act as files. Pipes 
are used for data transfers between 
processes. 


Device Drivers 


The system’s fourth level contains the device drivers. Device 
drivers handle basic I/O functions for specific I/O controller hard- 
ware. You can use pre-written drivers, or you can write your 
own. 
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Device Descriptors 


The system’s fifth level contains the device descriptors. Device 
descriptors are small tables that define the logical name, device 
driver, and file manager for each I/O port. They also contain port 
initialization and port address information. Device descriptors 
require only one copy of each I/O controller driver used. 


Shell 


The shell is the command interpreter. It is a program and not a 
part of the operating system. The shell is fully described in the 
OS-9 Commands manual. 
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The Kernel 


The kernel is the core of OS-9. The kernel supervises the system 
and manages system resources. Half of the kernel (called 
OS9P1) resides in the boot module. The other half of the kernel 
(called OS9P2) is loaded into RAM with the other OS-9 modules. 


The kernel’s main functions are: 
® System initialization after reset 
@ Service request processing 
@ Memory management 
® Multiprogramming management 
e Interrupt processing 


I/O functions are not included in the list because the kernel does 
not directly process them. Instead, it passes I/O system calls to 
the I/O Manager for processing. 


System Initialization 


After a hardware reset, the kernel initializes the system. This 
involves: 


1. Locating modules loaded in memory from the OS-9 Boot file. 
2. Determining the amount of available RAM. 


3. Loading any required modules that were not loaded from the 
OS-9 Boot file. 


OS-9 Level Two cannot install new system calls using the OS-9 
Level One system call F$SSvc. F$SSve does not work with a 
Level Two user program because of the separation of system and 
user address space. 
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OS9P3 can be used to tailor the system to fit specific needs. The 
following listing is an example of how to use the OS9P3 module. 


Microware 0S-9 Assembler 2.1 11/18/83 16:06:01 Page 004 


0S-9 Level TWO V1.2, part 2 - 0S-9 System Symbol Definitions 


00001 
00002 
00003 


O00 11 ARGUE GGG HARRAH RARER EERE EEE 


O0012 + 

00013 * Module Header 

00014 + 

00015 O0Ct Type set Systm+Objct 

00016 0081 Revs set Retnt+t 

00017 0000  87CDOOSE mod OS9End,OS9Name, Type Revs, Cold, cab 
00018 00D 4F533970  OS9Name fecs "“Q59p3" 

00019 

00029 @0i2 Of feb {1 edition number 

0030 use defsfile 

00031 0002 level equ 2 

00032 opt -c 

9033 opt f 

00041 

0042 I II AR RRR EER RRR A RHE 
00043 + 

00044 + Routine Cold 

00045 + 

00040 + 

00047 

00048 0013 318D0004 Cold leay SveTbl,per get service routine 
00049 0017 103F32 059 F$SSvc «install new service 
00050 O01A 39 rts 

00051 

0052 

00053 UAT RARER ARE EHH HE 
00054 «+ 

0005S = + Service Routines Initialization Table 
00056 +* 

00057 

0058 02s FSSAYHI equ $25 set up new call 

00059 + Add this to the user os9defs file, 

0060 


aan eee eee errr eer 
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00061 018 SvcTbl equ # 

00062 O01B 25 fob = FSSAYHI 
om $0063 O01C 0001 fdb SayHi-#-2 
| / 00064 QO1E 89 fob = $80 


Microware 05-9 Assembler 2.1 11/18/83 16:06:01 Page O02 
05-9 Level TWO V1.2, part 2 - 05-9 system Symbol Definitions 


10068 * 

00069 Service call Say Hello to user 

00070 * 

00071 Input: U = Registers ptr 

00072 ¢ R$X,u = Message ptr (if @ send default) 
00073 # Max message length = 40 bytes, 

00074 * 

00075 *Dutput: Message sent to standard error path of user. 
00076 ¢ 

0077 tData:  D.Proc 


0078 # 
c» 0079 
00080 O01F  AE44 sayHi ldx RSX ,u gel mess. address 
00081 9021 2619 bne sayHi6 bra if not default 


$0082 0023 109659 ldy D.Proc get proc descr ptr 
00083 0026 EE24 ldu PSSP,,y get caller's stack 
00084 0028  33C8D8 leau = -4u room for message 
00085 0028 96Da lda D.Systsk  system’s task num 
$0086 02D £626 ldb PSTASK,y caller's task num 
00087 O02F 10860028 ldy #49 set byte count 
00088 0033 308D0012 leax Hello,per destination ptr 
00089 0037 103F38 059 F§Move mess into user mem 
00090 003A 3004 leax Qu 
00091 G03C 10860028  SayHié ldy #49 get max byte count 
00092 0040 DESa ldu D.Proc get proc desc ptr 
00093 0042 A6C832 lda PSPATH+2,u path num of stderr 
00094 0045 103F8C 059 I$WritLn write mess line 
00095 0048 39 rts 
00096 

Cc 00097 0049 48656C6C Hello fee "Hello there user," 
00098 OSA aD fcb $)) 
0099 
00100 058 510486 emod module CRC 
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00102 OO5E 059End equ t 
00103 
00104 end 


$0000 error(s) 

00000 warning(s) 

$005E 00094 program bytes generated 
$0000 00000 data bytes allocated 
$2884 10372 bytes used for symbols 


System Call Processing 


System calls are used to communicate between OS-9 and assem- 
bly-language programs for such functions as memory allocation 
and process creation. In addition to I/O and memory manage- 
ment functions, system calls have other functions. These include 
interprocess control and timekeeping. 


System calls use the SWI2 instruction followed by a constant 
byte representing the code. You usually pass parameters for sys- 
tem calls in the 6809 registers. 


OS9Defs and Symbolic Names 


A system-wide assembly-language equate file, called OS9Defs, 
defines symbolic names for all system calls. This file is included 
when assembling hand-written or compiler-generated code. The 
OS-9 assembler has a built-in macro to generate system calls. 
For example: 


O0S9 I$Read 
is recognized and assembled as equivalent to: 


SWI2 
FCB I$¢Read 


The OS-9 assembly macro OS9 generates an SWI2 function. The 
label I$Read is the label for the code $89. 


Types of System Calls 


System calls are divided into two categories, I/O calls and func- 
tion calls. 
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I/O calls perform various input/output functions. The kernel 
passes calls of this type to the I/O manager for processing. The 
symbolic names for I/O calls begin with I$. For example, the 
Read system call is called I$Read. 


Function calls perform memory management, multi-program- 
ming, and other functions. Most are processed by the kernel. The 
symbolic names for function calls begin with F$. For example, 
the Link function call is called F$Link. 


The function calls include user calls and privileged system mode 
calls. (See Chapter 8, “System Calls”, for more information.) 


Memory Management 


Memory management is an important operating system function. 
Using memory modules, OS-9 manages the logical contents of 
memory and the physical assignment of memory to programs. 


All programs that are loaded must be in the memory module for- 
mat. This format allows OS-9 to maintain a module directory of 
all the programs in memory. The directory contains information 
about each module, including its name and address and the 
number of processes using it. The number of processes using a 
module is called the module’s link count. 


When a module’s link count is zero, OS-9 deallocates its part of 
memory and removes its name from the module directory. 


Memory modules are the foundation of OS-9’s modular software 
environment. Advantages of memory management are: 


@ Automatic runtime linking of programs to libraries of 
utility modules 

@ Automatic sharing of re-entrant programs 

@ Replacement of small sections of large programs into 
memory for update or correction 


Memory Use 


OS-9 reserves some space at the top and bottom of RAM for its 
own use. The amount depends on the sizes of system tables that 
are specified in the INIT module. 


2-5 


OS-9 Technical Reference 


OS-9 pools all other RAM into a free memory space. As the sys- 
tem allocates or deallocates memory, it dynamically takes it 
from or returns it to this pool. RAM does not need to be contig- 
uous because the memory management unit can dynamically 
rearrange memory addresses. 


The basic unit of memory allocation is the 256-byte page. OS-9 
always allocates memory in whole numbers of pages. 


The data structure that OS-9 Level Two uses to keep track of 
memory allocation is a 256-byte bit map. Each bit in this table 
is associated with a specific page of memory. A cleared bit indi- 
cates that the page is free and available for assignment. A set 
bit indicates that the page is in use (that no RAM is free at that 
address). OS-9 Level Two always allocates memory in 8192-byte 
increments. This is the smallest memory block that the memory 
management hardware supports. 


OS-9 automatically allocates memory when any of the following 
occurs: 


@ Program modules are loaded into RAM 
e Processes are created 


@ Processes execute system calls to request additional 
RAM 


@ OS-9 needs I/O buffers or larger tables 


OS-9 also has inverse functions to deallocate memory allocated 
to program modules, new processes, buffers, and tables. 


In general, memory for program modules and buffers is allocated 
from high addresses downward. Memory for process data areas is 
allocated from low addresses upward. 


Following, is a memory map of a typical system. Actual memory 
sizes and addresses can vary depending on the exact system 
configuration. 
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Color Computer OS-9 Typical Memory Map 


+ $7FFFF 
I/O Device Addresses 
+ $7FFO0O0 
Reserved I/O Devices 
+ $7FE80 
Reserved Common Memory 
+ $7FEO00 
OS-9 Kernel 
+ varies 
Bottom of Memory 
in a 128K System 
+ $60000 
Bottom of Memory 
in a 512K System 
+ $00000 


Figure 2.1 


Note: The high two pages of every logical address space 
contain the defined areas I/O Device Addresses, Reserved 
I/O Devices, and Reserved Common Memory. 


Memory Management Hardware 


The 8-bit CPU in the Color Computer 3 can directly address only 
64 kilobytes of memory using its 16 address lines (A0-A15). The 
Color Computer 3’s Memory Management Unit (MMU) extends 
the addressing capability of the computer by increasing the 
address lines to 19 (A0-A18). This lets the computer address up 
to 512 kilobytes of memory ($0-$7F FFF). 


The 512K address space is called the physical address space. The 
physical address space is subdivided into 8K blocks. The six high 
order address bits (A13-A18) define a block number. 
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OS-9 creates a logical address space of up to 64K for each task 
by using the FORK system call. Even though the memory 
within a logical address space appears to be contiguous, it might 
not be—the MMU translates the physical addresses to access 
available memory. Address spaces can also contain blocks of 
memory that are common to more than one map. 


The MMU consists of a multiplexer and a 16 by 6-bit RAM 
array. Each of the 6-bit elements in this array is an MMU task 
register. The computer uses these task registers to determine 
the proper 8-kilobyte memory segment to address. 


The MMU task registers are loaded with addressing data by the 
CPU. This data indicates the actual location of each 8-kilobyte 
segment of the current system memory. The task registers are 
divided into two sets consisting of eight registers each. Whether 
the task register select bit (TR bit) is set or reset, determines 
which of the two sets is to be used. 


The relation between the data in the task register and the gen- 
erated addresses is as follows: 


D5 | D4 | D3 | D2 | Dt | Do_ 


a 
Memory Address | Al18 | Al7 | A16 | Al15 |} Al4 | Al13 


Figure 2.2 


When the CPU accesses any memory outside the I/O and control 
range (XFFO0=XFFFF), the CPU address lines (A13-A15) and 
the TR bit determine what segment of memory to address. This 
is done through the multiplexer when SELECT is low. (See the 
following table.) 


When the CPU writes data to the MMU, AO-A3 determine the 
location of the MMU register to receive the incoming data when 
SELECT is high. The following diagram illustrates the operation 
of the Color Computer 3’s memory management: 
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DO0-D5 
CPU data 


A13-A15 
TR bit pb 


A0-A3 


SELECT 


Figure 2.3 
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The system uses the data from the MMU registers to determine 
the block of memory to be accessed, according to the following 


table: 


fen fed a eek ce rococoes|Eg 


A15 Al4 Al3 


0 
0 
0 
0 
1 
i 
1 
1 
0 
0 
0 
0 
1 
i 
i 
i 


PROOF rFROO]/FPHROOHFOO 


RPOrRMOrFRORO]/FPFOrFROrFOFS 


X0000-X1FFF 
X2000-X3FFF 
X4000-X5FFF 
X6000-X7FFF 
X8000-X9FFF 
XA000-XBFFF 
XC000-XDFFF 
XE000-XFFFF 


X0000-X1 FFF 
X2000-X3FFF 
X4000-XSFFF 
X6000-X7FFF 
X8000-X9FFF 
XA000-XBFFF 
XCO000-XDFFF 
XE000-XFFFF 


Figure 2.4 


MMU 
AddressRange Address 
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Range 


From 


00000 
02000 
04000 
06000 
08000 
0A000 
0C000 
OE000 


10000 
12000 
14000 
16000 
18000 
1A000 
1C000 
1000 


20000 
22000 
24000 
26000 
28000 
2A000 
2C000 
2000 


30000 
32000 
34000 
36000 
38000 


To 


O1FFF 
O3FFF 
O5FFF 
O7FFF 
OOF FF 
OBFFF 
ODFFF 
OFFFF 


11FFF 
13FFF 
15FFF 
17FFF 
19FFF 
1BFFF 
1DFFF 
1FFFF 


21FFF 
23FFF 
25FFF 
27FFF 
29FFF 
2BFFF 
2DFFF 
2FFFF 


SIFFF 
S3FFF 
S5FFF 
3T7TFFF 
SOFFF 


3A000 3BFFF 
3C000 3DFFF 


3EK000 
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Block Range 
Number From To 
00 40000 41FFF 
O01 42000 43FFF 
02 44000 45FFF 
03 46000 47FFF 
04 48000 49FFF 
05 4A000 4BFFF 
06 4C000 4DFFF 
07 4E000 4FFFF 
08 50000 51FFF 
09 52000 53FFF 
OA 54000 55FFF 
OB 56000 57FFF 
OC 58000 59FFF 
OD 5A000 5BFFF 
OE 5C000 5DFFF 
OF 5E000 5SFFFF 
10 60000 61FFF 
Lt 62000 63FFF 
12 64000 65FFF 
13 66000 67FFF 
14 68000 69FFF 
1B 6A000 6BFFF 
16 6C000 6DFFF 
Ly 6E000 6FFFF 
18 70000 71FFF 
19 72000 73FFF 
1A 74000 75FFF 
1B 76000 77FFF 
1C 78000 79FFF 
1D 7A000 7BFFF 
1E 7C000 7DFFF 
1F 7E0O00 7FFFF 
Figure 2.5 


The translation of physical address to 8K-blocks is as follows: 


Block 


Number 


20 
21 
22 
23 
24 
25 
26 
27 


28 
29 
2A 
2B 
2C 
2D 
2E 
2F 


30 
31 
32 
33 
34 
30 
36 
37 


38 
39 
3A 
3B 
3C 
3D 
3K 
3F 


ed 
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In order for the MMU to function, the TR bit at $FF90 must be 
cleared and the MMU must be enabled. However, before doing 
this, the address data for each memory segment must be loaded 
into the designated set of task registers. For example, to select a 
standard 64K map in the top range of the Color Computer 3’s 
512K RAM, with the TR bit set to 0, the following values must 
be panel into the MMU’s registers: 


aie Data Data Address 
Address — (Bin) Range 


FFAO 111000 70000-71F FF 
FFA1 111001 72000-73F FF 
111010 74000-75F FF 
111011 76000-77F FF 
111100 78000-79F FF 
LA EEO. 7A000-7BFFF 
LIt110 7C000-7DFFF 
i See el 7K000-7F FFF 


Figure 2.6 


Although this table shows MMU data in the range $38 to 3F, 
any data between $0 and $3F can be loaded into the MMU reg- 
isters to select memory addresses in the range 0 to $7FFFF, as 
illustrated by Figure 2.5. 


Normally, the blocks containing I/O devices are kept in the sys- 
tem map, but not in the user maps. This is appropriate for time- 
sharing applications, but not for process control. To directly 
access I/O devices, use the F$MspBlk system call. This call 
takes a starting block number and block count, and maps them 
into unallocated spaces of the process’s address space. The sys- 
tem call returns the logical address at which the blocks were 
inserted. 


For example, suppose a display screen in your system is allo- 
cated at extended addresses $7A000-$7DFFF (blocks 3D and 
3E). The following system call maps them into your address 
space: 


ldb #2 number of blocks 

Sales #3D starting block number 

059 F$MapBlk call MapBlk 

stu TOPorts Save address where mapped 
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On return, the U register contains the starting address at which 
the blocks were switched. For example, suppose that the call 
returned $4000. To access extended address $7A020, write to 
$4020. 


Other system calls that copy data to or from one task’s map to 
another are available, such as F$STABX and F$Move. Some of 
these calls are system mode privileged. You can unprotect them 
by changing the appropriate bit in the corresponding entry of 
the system service request table and then making a new system 
boot with the patched table. 


Multiprogramming 


OS-9 is a multiprogramming operating system. This means that 
several independent programs called processes can be executed at 
the same time. By issuing the appropriate system call to OS-9, 
each process can have access to any system resource. 


Multiprogramming functions use a hardware real-time clock. 
The clock generates interrupts 60 times per second, or one every 
16.67 milliseconds. These interrupts are called ticks. 


Processes that are not waiting for some event are called active 
processes. OS-9 runs active processes for a specific system- 
assigned period called a time slice. The number of time slices 
per minute during which a process is allowed to execute depends 
on a process’s priority relative to all other active processes. 
Many OS-9 system calls are available to create, terminate, and 
control processes. 


Process Creation 


A process is created when an existing process executes a Fork 
system call (F$Fork). This call’s main argument is the name of 
the program module that the new process is to execute first (the 
primary module). 


Finding the Module. OS-9 first attempts to find the module in 
the module directory. If it does not find the module, OS-9 usu- 
ally attempts to load into memory a mass-storage file in the exe- 
cution directory, with the requested module name as a filename. 
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Assigning a Process Descriptor. Once OS-9 finds the module, 
it assigns the process a data structure called a process descrip- 
tor. This is a 64-byte package that contains information about 
the process, its state (see the following section “Process States”), 
memory allocations, priority, queue pointers, and so on. OS-9 
automatically initializes and maintains the process descriptor. 
The process itself cannot access the descriptor; it has no need to 
do so. 


Allocate RAM. The next step is to allocate RAM for the pro- 
cess. The primary module’s header contains a storage size. OS-9 
uses this size unless the Fork system call requests a larger area. 
OS-9 then attempts to allocate a memory area of the specified 
size from the free memory space. The memory space does not 
need to be contiguous. 


Proceed or Terminate. If OS-9 can perform all of the previous 
steps, it adds the new process to the active process queue for exe- 
cution scheduling. If it cannot, it terminates the creation; the 
process that originated the Fork is informed of the error. 


Assign Process ID and User ID. OS-9 assigns the new process 
a unique number called a process ID. Other processes can com- 
municate with the process by referring to its ID in various sys- 
tem calls. 


The process also has a user ID, which is used to identify all pro- 
cesses and files belonging to a particular user. The user ID is 
inherited from the parent process. 


Process Termination. A process terminates when it executes 
an Exit system call (F$Exit) or when it receives a fatal signal. 
The termination closes any open paths, deallocates memory used 
by the process, and unlinks its primary module. 


Process States 
At any instant a process can be in one of three states: 
@ Active—The process is ready for execution. 


@ Waiting—The process is suspended until a child process 
terminates or until it receives a signal. A child process 
is a process that is started (execution is begun by) 
another process—a parent process. 
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@ Sleeping—The process is suspended for a specific period 
of time or until it receives a signal. 


Each state has its own queue, a linked list of descriptors of pro- 
cesses in that state. To change a process’s state, move its 
descriptor to another queue. 


The Active State. Each active process is given a time slice for 
execution, according to its priority. The scheduler in the kernel 
ensures that all active processes, even those of low priority, get 
some CPU time. 


The Wait State. This state is entered when a process executes a 
Wait system call (F$Wait). The process remains suspended until 
one of its child processes terminates or until it receives a signal. 
(See the “Signals” section later in this chapter.) 


The Sleeping State. This state is entered when a process exe- 
cutes a Sleep system call (F$Sleep), which specifies the number 
of ticks for which the process is to remain suspended. The pro- 
cess remains asleep until the specified time has elapsed or until 
it receives a wakeup signal. 


Execution Scheduling 


The OS-9 scheduler uses an algorithm that ensures that all 
active processes get some execution time. 


All active processes are members of the active process queue, 
which is kept sorted by process age. Age is the number of process 
switches that have occurred since the process’s last time slice. 
When a process is moved to the active process queue from 
another queue, its age is set according to its priority—the higher 
the priority, the higher the age. 


Whenever a new process becomes active, the ages of all other 
active processes increase by one time slice count. When the exe- 
cuting process’s time slice has elapsed, the scheduler selects the 
next process to be executed (the one with the next highest age, 
the first one in the queue). At this time, the ages of all other 
active processes increase by one. Ages never go beyond 255. 


A new active process that was terminated while in the system 
state is an exception. This process is given high priority because 
it is usually executing critical routines that affect shared system 
resources. 
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When there are no active processes, the kernel handles the next 
interrupt and then executes a CWA1 instruction. This procedure 
decreases interrupt latency time (the time it takes the system to 
process an interrupt). 


Signals 


A signal is an asynchronous control mechanism used for inter- 
process communication and control. It behaves like a software 
interrupt. It can cause a process to suspend a program, execute 
a specific routine, and then return to the interrupted program. 


Signals can be sent from one process to another process by the 
Send system call (F$Send). Or, they can be sent from OS-9 ser- 
vice routines to a process. 


A signal can convey status information in the form of a 1-byte 
numeric value. Some signal codes (values) are predefined, but 
you can define most. The signal codes are: 


0 = Kill (terminates the process, is non- 
interceptable) 


i = Wakeup (wakes up a sleeping process) 
2 = Keyboard terminate 
3 = Keyboard interrupt 
4 = Window change 
128-255 = User defined 


When a signal is sent to a process, the signal is saved in the 
process descriptor. If the process is in the sleeping or waiting 
state, it is changed to the active state. When the process gets its 
next time slice, the signal is processed. 


What happens next depends on whether or not the process has 
set up a signal intercept trap (signal service routine) by execut- 
ing an Intercept system call (F$lIcpt). 


If the process has set up a signal intercept trap, the process 
resumes execution at the address given in the Intercept call. The 
signal code passes to this routine. Terminate the routine with 
an RTI instruction to resume normal execution of the process. 
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Note: A wakeup signal activates a sleeping process. It sets 
a flag but ignores the call to branch to the intercept 
routine. 


If it has not set up a signal intercept trap, the process is termi- 
nated immediately. It is also terminated if the signal code is 
zero. If the process is in the system mode, OS-9 defers the termi- 
nation. The process dies upon return to the user state. 


A process can have a signal pending (usually because the pro- 
cess has not been assigned a time slice since receiving the sig- 
nal). If it does, and another process tries to send it another 
signal, the new signal is terminated, and the Send system call 
returns an error. To give the destination process time to process 
the pending signal, the sender needs to execute a Sleep system 
call for a few ticks before trying to send the signal again. 


Interrupt Processing 


Interrupt processing is another important function of the kernel. 
OS-9 sends each hardware interrupt to a specific address. This 
address, in turn, specifies the address of the device service rou- 
tine to be executed. This is called vectoring the interrupt. The 
address that points to the routine is called the vector. It has the 
same name as the interrupt. 


The SWI, SWI2, and SWI38 vectors point to routines that read 
the corresponding pseudo vector from the process’s descriptor 
and dispatch to it. This is why the Set SWI system call 
(F$SSWI) is local to a process; it only changes a pseudo vector in 
the process descriptor. 


Hardware Vector 


Table 
Vector Address 
SWI3 $FFF2 
SWI12 S$FFF4 
FIRQ $FFF6 
IRQ S$FFF8 
SWI SFFFA 
NMI S$FFFC 


RESTART $FFFE 
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FIRQ Interrupt. The system uses the FIRQ interrupt. The 
FIRQ vector is not available to you. The FIRQ vector is reserved 
for future use. Only one FIRQ generating device can be in the 
system at a time. 


Logical Interrupt Polling System 


Because most OS-9 I/O devices use IRQ interrupts, OS-9 
includes a sophisticated polling system. The IRQ polling system 
automatically identifies the source of the interrupt, and then exe- 
cutes its associated user- or system-defined service routine. 


IRQ Interrupt. Most OS-9 I/O devices generate IRQ interrupts. 
The IRQ vector points to the real-time clock and the keyboard 
scanner routines. These routines, in turn, jump to a special IRQ 
polling system that determines the source of the interrupt. The 
polling system is discussed in the next section, “Logical Inter- 
rupt Polling System.” 


NMI Interrupt. The system uses the NMI interrupt. The NMI 
vector, which points to the disk driver interrupt service routine, 
is not available to you. 


The Polling Table. The information required for IRQ polling is 
maintained in a data structure called the IRQ polling table. The 
table has a 9-byte entry for each device that might generate an 
IRQ interrupt. The table size is permanent and is defined by an 
initialization constant in the INIT module. Each entry in the 
polling table is given a number from 0 (lowest priority) to 255 
(highest priority). In this way, the more important devices (those 
that have a higher interrupt frequency) can be polled before the 
less important ones. 


Each entry has six variables: 


Polling Address Points to the status register of the device. 
The register must have a bit or bits that 
indicate if it is the source of an interrupt. 


Flip Byte Selects whether the bits in the device status 
register indicate active when set or active 
when cleared. If a bit in the flip byte is set, 
it indicates that the task is active whenever 
the corresponding bit in the status register 
is clear. 
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Mask Byte Selects one or more interrupt request flag 
bits within the device status register. The 
bits identify the active task or device. 


Service Points to the interrupt service routine for Uo 
Routine Address the device. You supply this address. 


Static Points to the permanent storage area 
Storage Address' required by the device service routine. You 
supply this address. 


Priority Sets the order in which the devices are 
polled (a number from 0 to 255). 


Polling the Entries. When an IRQ interrupt occurs, OS-9 
enters the polling system via the corresponding RAM interrupt 
vector. It starts polling the devices in order of priority. OS-9 
loads the status register address of each entry into Accumulator 
A, using the device address from the table. 


OS-9 performs an exclusive-OR operation using the flip byte, fol- 
lowed by a logical-AND operation using the mask byte. If the 
result is non-zero, OS-9 assumes that the device is the source of | 
the interrupt. w/ 


OS-9 reads the device memory address and service routine 
address from the table, and performs the interrupt service 
routine. 


Note: If you are writing your own device driver, terminate 
the interrupt service routine with an RTS instruction, not 
an RTI instruction. 


Adding Entries to the Table. You can make entries to the IRQ 
(interrupt request) polling table by using the Set IRQ system 
call (F$IRQ). Set IRQ is a privileged system call, OS-9 can exe- 
cute it only in the system mode. OS-9 is in system mode when- 
ever it is running a device driver. 


Note: The code for the interrupt polling system is located 
in the I/O Manager module. The OS9P1 and OS9P2 mod- 
ules contain the physical interrupt processing routines. 
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Virtual Interrupt Processing 


A virtual IRQ, or VIRQ, is useful with devices in Multi-Pak 
expansion slots. Because of the absence of an IRQ line from the 
Multi-Pak interface, these devices cannot initiate physical inter- 
rupts. VIRQ enables these devices to act as if they were inter- 
rupt driven. Use VIRQ only with device driver and pseudo device 
driver modules. VIRQ is handled in the Clock module, which 
handles the VIRQ polling table and installs the FSVIRQ system 
call. Since the F$VIRQ system call is dependent on clock initial- 
ization, the CC3GO module forces the clock to start. 


The virtual interrupt is set up so that a device can be inter- 
rupted at a given number of clock ticks. The interrupt can occur 
one time, or can be repeated as long as the device is used. 


The F$VIRQ system call installs VIRQ in a table. This call 
requires specification of a 5-byte packet for use in the VIRQ 
table. This packet contains: 


@ Bytes for an actual counter 
@ A reset value for the counter 


e A status byte that indicates whether a virtual interrupt 
has occurred and whether the VIRQ is to be re-installed 
in the table after being issued 


F$VIRQ also specifies an initial tick count for the interrupt. 
The actual call is summarized here and is described in detail in 
Chapter 8. 


Call: OSI F$VIRQ 

Input: (Y) = address of 5-byte packet 
(X) = 0 to delete entry, 1 to install entry 
(D) = initial count value 


Output: none 
(CC) carry set on error 
(IS) appropriate error code 


The 5-byte packet is defined as follows: 


Name Offset Function 

Vi,Cnt $0 Actual counter 

Vi.Rst $2 Reset value for counter 
Vi.Stat $4 Status byte 
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Two of the bits in the status byte are used. These are: 


Bit O - set if VIRQ occurs 
Bit 7 - set if a count reset is required 


When making an F$VIRQ call, the packet might require initial- 
ization with a reset value. Bit 7 of the status byte must be 
either set or cleared to signify a reset of the counter or a one- 
time VIRQ call. The reset value does not need to be the same as 
the initial counter value. When OS-9 processes the call, it writes 
the packet address into the VIRQ table. 


At each clock tick, OS-9 scans the VIRQ table and subtracts one 
from each timer value. When a timer count reaches zero, OS-9 
performs the following actions: 


1. Sets Bit 0 in the status byte. This specifies a Virtual IRQ. 
2. Checks Bit 7 of the status byte for a count reset request. 


3. If bit 7 is set, resets the count using the reset value. If bit 7 
is reset, deletes the packet address from the VIRQ table. 


When a counter reaches zero and makes a virtual interrupt 
request, OS-9 runs the standard interrupt polling routine and 
services the interrupt. Because of this, you must install entries 
on both the VIRQ and DIRQ polling tables whenever you are 
using a VIRQ. 


Unless the device has an actual physical interrupt, install the 
device on the IRQ polling table via the F$IRQ system call before 
placing it on the VIRQ table. 


If the device has a physical interrupt, use the interrupt’s hard- 
ware register address as the polling address for the F$IRQ call. 
After setting the polling address, set the flip and mask bytes for 
the device, and make the F$IRQ call. 


If the device is totally VIRQ-driven, and has no interrupts, use 
the status byte from the VIRQ packet as the status byte. Use a 
mask byte of %00000001, defined as Vi.IFlag in the defs file. 
Use a flip byte value of 0. The following examples show how to 
set up both types of VIRQ calls. The first example is taken from 
an ACIA-type driver that has a physical interrupt found in a 
status register, but that cannot be accessed by the processor if 
used in the Multi-Pak. The second example is for a device with 
no physical interrupt handling, all interrupts are handled 
through the VIRQ. 
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* VIRG Example #1 - Device Driver possessing real [RQ’s 


Copyright 1985, 1986 by Microware Systems 
* Corporation. Reproduced Under License 


use defsfile 


* actual mask byte for hardware interrupt 
IRQReq set 110000000 Interrupt Request 


* offset to the actual hardware status register 
Status equ | 


* VIRQ countdown value 
VIRQCNT equ | do the VIRQ on every tick 


KEEKKEHKEEEEKRHEEHREESE 
* Static storage offsets 


* 


org V.oCF room for scf variables 


VIRQBUF rmb 5 buffer for fake interrupt from clock 


MEM equ. Total static storage requirement 


HHEKKEHREHEEEEERES 

* Module Header 

mod MEND,NAM,DRIVR+OBJCT,REENT+1 ,ENT,MEM 
feb UPDAT. 


fob Edition Current Revision 
EEEEKEEERERREREREEEEEEEESE 
* Driver entry jump table 
ENT lbra INIT 

bra READ 

lbra WRITE 

lbra GETSTA 
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bra PUTSTA 
bra TRMNAT 


* Actual mask information for F$IRQ call for the 
* hardware interrupt MASK fcb @ no flip bits 

* fcb IRQReg Irq polling mask 

* fob 1@ (higher) priority 


KEEKKHEKEKEEHRHEESE 

+ [nit 

+ Initialize the device 

* Includes setting up the IR@ and VIRQ entries 


* 


INIT 


* Install IRQ polling Table Entry first 
* Use the hardware status register and the hardware 
* mask 

Idd V.PORT,U get port address in D 

add #Status point to hardware status byte 

leax MASK,PCR get the hardware interrupt mask 

leay MIRQ,PCR address of interrupt service routine 
0S9 FS$IRQ Add to IRQ polling table 

bes INIT9 error - return it 


* Install VIRQ in Clock Module second 
* 

leay VIRQBUF,U get the 5 byte VIRQ buffer pointer 

Ida #$80 get reset flag for repeated VIRQ’s 

sta Vi.Stat,y put it into buffer 

Idd #VIRQCNT get count for number of ticks for the VIRQ 
std Vi.Rst,y put in initial reset value 

Idx #1 put onto table 

os9 FSVIRG make the service request 

bes INIT9 Error - return it 


INITS rts 


READ 


2-22 


The Kernel / 2 


WRITE 


Mm GETSTA 
PUTSTA 


HEEKKHEHEEEEEHES 


* Subroutine TRMNAT 


Terminate device, including removal from tables 
% 


TRMNAT 


* remove from VIRQ table first 

ldx #2 remove from VIRG table 

leay VIRQBUF ,U get address 

059 FSVIRQ remove modem from VIRQ table 
* next remove from IRQ table 

Idx #9 

ma O59 FSIRQ remove modem from polling tbl 

rts 


RHEE KKHEHHEEEEHEHHER ES 


+ MIRQ 


* process Interrupt 
¥ 


MDIRG 


« actual interrupt service routine > 


rts 


emod Module Cre 
MEND equ * 


a 


* VIRG Example #2 - Device Driver without hardware interrupts 
HRHEEKEHRERERERES 


* STATIC STORAGE DEFINITION 


* 
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VIRQGBF rmb S buffer for VIRQ 
DMEM equ . 


HREEHREKHREKERHREREERE 

* Module Header 

% 

mod DEND,DNAM,DRIVR+OBUCT,REENT+REV, DENT , DMEM 
fob UPDAT. mode byte 


fob 3 EDITION BYTE 


* Driver entry table 

DENT lbra INIT initialize 
lbra READ 
lbra WRITE 
lbra GETSTAT get status 
lbra SETSTAT set status 
lbra TERM terminate 


* Mask information packet for FSIRQ call 
* NOTE: uses the virtual interrupt flag, Vi.IFlag, for 
* the maskbyte 
* 
DMSK fcb @ no flip bits 
feb Vi. IFlag polling mask for VIRQ 
fob 18 priority 


HHEHRHKKHEEEEEEEEEE 


* INITIALIZE STORAGE AND CONTROLLER 
* Includes setting up the IRQ and VIRQ table entries 


* 


INIT 


* set up IRQ table entry first 

* NOTE: uses the status register of the VIRQ buffer for 
* the interrupt status register since no hardware status 
* register is available 


leay VIRQBF+Vi.Stat,U get address of status byte 


a aaaaaaaaaaaaacacaaacacaaaaaaasaaaaaaaaaa 
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ifr y,d put it into D reg 

leay DIRG,PCR get address of interrupt routine 
leax DMSK,PCR get VIRQ mask info 

059 F$IRQ install onto table 

bes INIT9 exit on error 


* now set up the VIRQ table entry 

leay VIRQBF,U point to the S-byte packet 

Ida #$80 get the reset flag to repeat VIRQ’s 

sta Vi.Stat,y save it in the buffer 

Idd #VIRQCNT get the VIR@ counter value 

std Vi.Rst,y save it in the reset area of buffer 
Idx #1 code to install the VIRQ 

059 FS$VIRQ install on the table 

bes INIT9 exit on error 


INIT rts 


READ 
WRITE 
GETSTAT 
PUTSTAT 


RHEE RRRHEREERHREEEE 

* TERM - terminate the device and remove entries from 
* tables 

TERM 


* remove from VIRQ table first 
Idx #0 get zero to remove from table 
leay VIRQBF,U get address of packet 
059 FSVIRQ 
* then remove from IRQ table 
Idx #@ get zero to remove from table 
os9 FSIRGQ 


rts 


KREREREEREEEEEREEEREREREREREERRRERERRRRREEER ERR EEERE REESE 
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* DIRQ - interrupt service routine 


* NOTE: The service routine must be sure to reset the 
* status byte of the VIRQ packet so that the interrupt 


* looks as if it is cleared. 
¥ 


DIRQ 


Ida VIRGBF+Vi.Stat,U get status byte 
anda #$FF-Vi.IFlag mask off interrupt bit 
sta VIRQBF+Vi.Stat,U put it back 


rts 


EMOD 
DEND equ # 


END 
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Chapter 3 
Memory Modules 


In Chapter 2, you learned that OS-9 is based on the concept that 
memory is modular. This means that each program is considered 
to be an individually named object. 


You also learned that each program loaded into memory must be 
in the module format. This format lets OS-9 manage the logical 
contents of memory, as well as the physical contents. Module 
types and formats are discussed in detail in this chapter. 


Module Types 


There are several types of modules. Each has a different use and 
function. These are the main requirements of a module: 


® It cannot modify itself. 


e It must be position-independent so that OS-9 can load or 
relocate it wherever space is available. In this respect, 
the module format is the OS-9 equivalent of load records 
used in older operating systems. 


A module need not be a complete program or even 6809 machine 
language. It can contain BASICO09 I-code, constants, single sub- 
routines, and subroutine packages. 


Module Format 


Each module has three parts: a module header, a module body, 
and a cyclic-redundancy-check value (CRC value). 
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Module Header 


Program 
or 
Constants 


CRC Value 


Figure 3.1 


Module Header 


At the beginning of the module (the lowest address) is the mod- 
ule header. Its form depends upon the module’s use. 


The header contains information about the module and its use. 
This information includes the following: 


@ Size 

@ Type (machine code, BASICO9 compiled code, and so on) 
e Attributes (executable, re-entrant, and so on) 

e Data storage memory requirements 

e Execution starting address 


Usually, you do not need to write routines to generate the mod- 
ules and headers. All OS-9 programming languages automati- 
cally create modules and headers. 


Module Body 


The module body contains the program or constants. It usually 
is pure code. The module name string is included in this area. 
Figure 3.2 provides the offset values for calculating the location 
of a module’s name. (See “Offset to Module Name”) 


CRC Value 


The last three bytes of the module are the Cyclic Redundancy 
Check (CRC) value. The CRC value is used to verify the integ- 
rity of a module. 
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When the system first loads the module into memory, it per- 
forms a 25-bit CRC over the entire module, from the first byte of 
the module header to the byte immediately before the CRC. The 
CRC polynomial used is $800FE3. 


As with the header, you usually don’t need to write routines to 
generate the CRC value. Most OS-9 programs do this 
automatically. 


Module Headers: Standard Information 


The first nine bytes of all module headers are defined as follows: 


Relative 
Address Use 
$00,$01 Sync bytes ($87,$CD) 
$02,$03 Module size 
$04,$05 Offset to module name 
$06 Module type/Language 
$07 Attributes/Revision level 
$08 Header check 

Figure 3.2 

Sync Bytes 


The sync bytes specify the location of the module. (The first sync 
byte is the start of the module.) These two bytes are constant. 


Module Size 


The module size specifies the size of the module in bytes 
(includes CRC). 


Offset to Module Name 


The offset to module name specifies the address of the module 
name string relative to the start of the module. The name string 
can be located anywhere in the module. It consists of a string of 
ASCII characters with the most significant bit set on the last 
character. 
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Type/Language Byte 


The type/language byte specifies the type and language of the 
module. 


The four most significant bits of this byte indicate the type. 
Eight types are pre-defined. Some of these are for OS-9’s inter- 
nal use only. The type codes are given here (0 is not a legal type 
code): 


Code Module Type sNasme 
$1x Program module Prgrm 
$2x Subroutine module Sbrtn 
$3x Multi-module (for future use) Multi 
$4x Data module Data 
$5x-$Bx User-definable module 
$Cx OS-9 system module Systm 
$Dx OS-9 file manager module FlMgr 
$Ex OS-9 device driver module Drivr 
$F*x OS-9 device descriptor module Devic 
Figure 3.3 


The four least significant bits of Byte 6 indicate the language 
(denoted by x in the previous Figure). The language codes are 
given here: 


Code Language 

$x0 Data (non-executable) 

$x1 6809 object code 

$x2 BASICO09 I-code 

$x3 PASCAL P-code 

$x4-$xF Reserved for future use 
Figure 3.4 


By checking the language type, high-level language runtime 
systems can verify that a module is the correct type before 
attempting execution. BASIC09, for example, can run either I- 
code or 6809 machine language procedures arbitrarily by check- 
ing the language type code. 


Attributes/Revision Level Byte 


The attributes/revision level byte defines the attributes and revi- 
sion level of the module. 
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The four most significant bits of this byte are reserved for mod- 
ule attributes. Currently, only Bit 7 is defined. When set, it indi- 
cates the module is re-entrant and, therefore, shareable. 


The four least significant bits of this byte are a revision level in 
the range 0 to 15. If two or more modules have the same name, 
type, language, and so on, OS-9 keeps in the module directory 
only the module having the highest revision level. Therefore, you 
can replace or patch a ROM module, simply by loading a new, 
equivalent module that has a higher revision level. 


Note: A previously linked module cannot be replaced until 
its link count goes to zero. 


Header Check 


The header check byte contains the one’s complement of the 
Exclusive-OR of the previous eight bytes. 


Module Headers: Type-Dependent 
Information 


More information usually follows the first nine bytes of a module 
header. The layout and meaning vary, depending on the module 


type. 
Module types $Cx-$Fx (system module, file manager module, 


device driver module, and device descriptor module) are used 
only by OS-9. Their formats are given later in the manual. 


Module types $1x through $Bx have a general-purpose executa- 
ble format. This format is often used in programs called by 
F$Fork or F$Chain. Here is the format used by these module 


types: 
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Executable Memory Module Format 


Relative Check 
Address Use Range we 


$00 

Sync Bytes ($87,$CD) 
$01 
$02 

Module Size (bytes) 
$03 
$04 

Module Name Offset header 
$05 parity 


$08 Header Parity Check CRC 
ww 
$09 
Execution Offset 
$0A 
$0B 
Permanent Storage Size 
$0C 
$0D (Additional optional header 
extensions) 
Module Body 
object code, constants, 
and so on 
CRC Check Value , 


Figure 3.5 


LO 
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As you can see from the preceding chart, the executable memory 
has four extra bytes in its header. They are: 


$09, $0A Execution offset 
$0B,$0C Permanent storage size 


Execution Offset. The program or subroutine’s offset starting 
address, relative to the first byte of the sync code. A module that 
has multiple entry points (such as cold start and warm start) 
might have a branch table starting at this address. 


Permanent Storage Size. The minimum number of bytes of 
data storage required to run. Fork and Chain use this number 
to allocate a process’s data area. 


If the module is not directly executed by a Fork or Chain system 
call (for instance a subroutine package), this entry is not used by 
OS-9. It is commonly used to specify the maximum stack size 
required by re-entrant subroutine modules. The calling program 
can check this value to determine if the subroutine has enough 
stack space. 


When OS-9 starts after a single system reset, it searches the 
entire memory space for ROM modules. It finds them by looking 
for the module header sync code ($87,$CD). 


When OS-9 detects the header sync code, it checks to see if the 
header is correct. If it is, the system obtains the module size 
from the header and performs a 24-bit CRC over the entire mod- 
ule. If the CRC matches, OS-9 considers the module to be valid 
and enters it into the module directory. All ROM modules that 
are present in the system at startup are automatically included 
in the system module directory. 


After the module search, OS-9 links to the component modules it 
found. This is the secret to OS-9’s ability to adapt to almost any 
6809 computer. It automatically locates its required and optional 
component modules and rebuilds the system each time it is 
started. 
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Chapter 4 


OS-9’s Unified 
Input/Output System 


Chapter 1 mentioned that OS-9 has a unified I/O system, con- 
sisting of all modules except those on the kernel level. This chap- 
ter discusses the I/O modules in detail. 


I/O System Modules 
: Serene, 


Input/Output Manager 
(OMAN) 


Disk File 
Manager 
(RBF) 


Pipe File 
Manager 
(Pipeman) 


Char. File 
Manager Printer $10 
(SCF) 


ACIAPak ModPak CC3I0 
Driver Driver 
Driver Driver 


[off e][|[oe][e][_ ree] [of 


RBF Device Descriptors Pipe Descr. SCF Device Descriptors 


CC3Disk 
Disk 


CC3Hdisk 
Disk 


Ram 
Ram Disk 
Driver 


VdgInt Grflnt Windlnt 


CC310 CC310 CC3I0 
Interface Interface Interface 


Term_Vdg 
Desc 
Eee 
Desc 


OS-9 COMPONENT MODULE ORGANIZATION 
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The VDG Interface performs both interface and low level routines 
for VDG Color Computer 2 compatible modes and has limited 
support for high res screen allocation. 


The GrfInt Interface provides the standard code interpretations 
and interface functions. 


The WindInt Interface, available in the Multi-view package, con- 
tains all the functionality of GrfInt, along with additional sup- 
port features. If you use WindInt, do not include GrfInt. 


Both WindInt and GrfInt use the low-level driver GrfDrv to per- 
form drawing on the bit-map screens. 


Term__VDG uses CC3IO/VdgInt while Term—win and all win- 
dow descriptors use CC3IO/(WindInt/GrfInt)/GrfDrv modules. 


The I/O system provides system-wide, hardware-independent I/O 
services for user programs and OS-9 itself. All I/O system calls 
are received by the kernel and passed to the I/O manager for 
processing. 


The I/O manager performs some processing, such as the alloca- 
tion of data structures for the I/O path. Then, it calls the file 
managers and device drivers to do most of the work. Additional 
file manager, device driver, and device descriptor modules can be 
loaded into memory from files and used while the system is 
running. 


The I/O Manager 


The I/O manager provides the first level of service of I/O system 
calls. It routes data on I/O process paths to and from the appro- 
priate file managers and device drivers. 


The I/O Manager also maintains two important internal OS-9 
data structures—the device table and the path table. Never mod- 
ify the I/O manager. 


When a path is opened, the I/O manager tries to link to a mem- 
ory module that has the device name given or implied in the 
pathlist. This module is the device descriptor. It contains the 
names of the device driver and file manager for the device. The 
I/O manager saves the names so later system calls can be routed 
to these modules. 
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File Managers 


OS-9 can have any number of file manager modules. Each of 
these modules processes the raw data stream to or from a class 
of device drivers that have similar operational characteristics. It 
removes aS many unique characteristics as possible from I/O 
operations. Thus, it assures that similar devices conform to the 
OS-9 standard I/O and file structure. 


The file manager also is responsible for mass storage allocation 
and directory processing, if these are applicable to the class of 
devices it serves. 


File managers usually buffer the data stream and issue requests 
to the kernel for dynamic allocation of buffer memory. They can 
also monitor and process the data stream, for example, adding 
line-feed characters after carriage-return characters. 


The file managers are re-entrant. The three standard OS-9 file 
managers are: 


@ Random block file manager: The RBF manager supports 
random-access, block-structured devices such as disk sys- 
tems and bubble memories. (Chapter 5 discusses the 
RBF manager in detail.) 


® Sequential Character File Manager: The SCF manager 
supports single-character-oriented devices, such as CRTs 
or hardcopy terminals, printers, and modems. (Chapter 6 
discusses SCF in detail.) 


@ Pipe File Manager (PIPEMAN): The pipe manager sup- 
ports interprocess communication via pipes. 


File Manager Structure 


Every file manager must have a branch table in exactly the fol- 
lowing format. Routines that are not used by the file manager 
must branch to an error routine, that sets the carry and loads 
Register B with an appropriate error code before returning. Rou- 
tines returning without error must ensure that the carry bit is 
clear. 
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* All routines are entered with: 
* CY) = Path Descriptor pointer 
* CU) = Caller’s register stack pointer 


Enteyrt sequ. * 
lbra Create 
lbra Open 
lbra MakDir 
lbra ChgDir 
lbra Delete 
lbra Seek 
lbra Read 
lbra Write 
lbra ReadLn 
lbra WriteLn 
lbra GetStat 
lbra PutStat 
lbra Close 


Create, Open 


Create and Open handle file creating and opening for devices. 
Typically, the process involves allocating any required buffers, 
initializing path descriptor variables, and establishing the path 
name. If the file manager controls multi-file devices (RBF), 
directory searching is performed to find or create the specified 
file. 


Makdir 


Makdir creates a directory file on multi-file devices. Makdir is 
neither preceded by a Create nor followed by a Close. File man- 
agers that are incapable of supporting directories need to return 
carry set with an appropriate error code in Register B. 


ChgDir 


On multi-file devices, ChgDir searches for a directory file. If 
ChgDir finds the directory, it saves the address of the directory 
(up to four bytes) in the caller’s process descriptor. The descrip- 
tor is located at P$DIO+2 (for a data directory) or P$DIO+8 
(for an execution directory). 


ww 
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In the case of the RBF manager, the address of the directory’s 
file descriptor is saved. Open/Create begins searching in the cur- 
rent directory when the caller’s pathlist does not begin with a 
slash (/). File managers that do not support directories should 
return the carry set and an appropriate error code in Register 
B. 


Delete 


Multi-file device managers handle file delete requests by initiat- 
ing a directory search that is similar to Open. Once a device 
manager finds the file, it removes the file from the directory. 
Any media in use by the file are returned to unused status. In 
the case of the RBF manager, space is returned for system use 
and is marked as available in the free cluster bit map on the 
disk. File managers that do not support multi- file devices 
return an error. 


Seek 


File managers that support random access devices use Seek to 
position file pointers of an already open path to the byte speci- 
fied. Typically, the positioning is a logical movement. No error is 
produced at the time of the seek if the position is beyond the 
current “end of file”. 


Normally, file managers that do not support random access 
ignore Seek. However, an SCF-type manager can use Seek to 
perform cursor positioning. 


Read 


Read returns the number of bytes requested to the user’s data 
buffer. Make sure Read returns an EOF error if there is no data 
available. Read must be capable of copying pure binary data, and 
generally performs no editing on the data. Generally, the file 
manager calls the device driver to actually read the data into 
the buffer. Then, the file manager copies the data from the buffer 
into the user’s data area to keep file managers device- 
independent. 
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Write 


The Write request, like Read, must be capable of recording pure 
binary data without alteration. The routines for Read and Write 
are almost identical with the exception that Write uses the 
device driver’s output routine instead of the input routine. The 
RBF manager and similar random access devices that use fixed- 
length records (sectors) must often preread a sector before writ- 
ing it, unless they are writing the entire sector. In OS-9, writing 
past the end of file on a device expands the file with new data. 


ReadLn 


ReadLn differs from Read in two respects. First, ReadLn termi- 
nates when the first end-of-line (carriage return) is encountered. 
ReadLn performs any input editing that is appropriate for the 
device. In the case of SCF, editing involves handling functions 
such as backspace, line deletion, and the removal of the high- 
order bit from characters. 


WriteLn 


WriteLn is the counterpart of ReadLn. It calls the device driver 
to transfer data up to and including the first (if any) carriage 
return encountered. Appropriate output editing can also be per- 
formed. For example, SCF outputs a line feed, a carriage return 
character, and nulls (if appropriate for the device). It also pauses 
at the end of a screen page. 


GetStat, PutStat 


The GetStat (get status) and PutStat (put status) system calls 
are wildcard calls designed to provide a method of accessing fea- 
tures of a device (or file manager) that are not generally device 
independent. The file manager can perform specific functions 
such as setting the size of a file to a given value. Pass unknown 
status calls to the driver to provide further means of device inde- 
pendence. For example, a PutStat call to format a disk track 
might behave differently on different types of disk controllers. 
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Close 


Close is responsible for ensuring that any output to a device is 
completed. (If necessary, Close writes out the last buffer.) It 
releases any buffer space allocated in an Open or Create. Close 
does not execute the device driver’s terminate routine, but can 
do specific end-of-file processing if you want it to, such as writ- 
ing end-of-file records on disks, or form feeds on printers. 


Interfacing with Device Drivers 


Strictly speaking, device drivers must conform to the general for- 
mat presented in this manual. The I/O Manager is slightly dif- 
ferent because it only uses the Init and Terminate entry points. 
Other entry points need only be compatible with the file man- 
ager for which the driver is written. For example, the Read entry 
point of an SCF driver is expected to return one byte from the 
device. The Read entry point of an RBF driver, on the other 
hand, expects Read to return an entire sector. 


The following code is part of an SCF file manager. The code 
shows how a file manager might call a driver. 
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KHHEKEKKKHHEKKKHEKEEE 


* I[OEXEC 

* Execute Device’s Read/Write Routine 

* 

+ Passed: CA) = Qutput character Cwrite) 

* CX)? = Device Table entry: pir 

* CY? = Path Déeseripitor. pointer 

* CU) = Offset of routine CD$Read, 


D¢Write)d 
Input char Cread) 
Error code, CC Set af -error 


* Returns: CA) 
* (CB) 
* Destroys B,CC 


IQDEXEC. pshs €4,%.Vs4 save registers 

ldu VSSTATsx get static storage tor driver 
ldx V$DRIV,x get driver module address 

ldd M$EXEC,x and offset of execution entries 
addd 5,5 offset by read/write 

leax d,x absolute entry address 

lda ,5+ restore char Cfor write) 

far 0, % execute driver read/write 

Puls ek Y5Uspe return CAd=cnar, K<B2erpor 


emod Module CRC 
Size @€0u * Size of sequential Tile manager 


Device Driver Modules 


The device driver modules are subroutine packages that perform 
basic, low-level I/O transfers to or from a specific type of I/O 
device hardware controller. These modules are re-entrant. So, 
one copy of the module can concurrently run several devices that 
use identical I/O controllers. 


Device driver modules use a standard module header, in which 
the module type is specified as code $Ex (device driver). The exe- 
cution offset address in the module header points to a branch 
table that has a minimum of six 3-byte entries. 


Each entry is typically an LBRA to the corresponding subrou- 
tine. The file managers call specific routines in the device driver 
through this table, passing a pointer to a path descriptor and 
passing the hardware control register address in the 6809 regis- 
ters. The branch table looks like this: 


wo 


Code 


+ $00 
+ $03 
+ $06 
+ $09 
+ $0C 
+ $0F 
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Meaning 


Device initialization routine 
Read from device 

Write to device 

Get device status 

Set device status 

Device termination routine 


(For a complete description of the parameters passed to these 
subroutines, see the “Device Driver Subroutines” sections in 
Chapters 5 and 6.) 
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Device Driver Module Format 


Relative Check 
Address Use Range 
$00 

Sync Bytes ($87,$CD) 
$01 
$02 

Module Size (bytes) 
$03 
$04 

Module Name Offset Header 
$05 Parity 


$08 Header Parity Check CRC 


$09 
Execution Offset 
$0A 
$0B 
Permanent Storage Size 
$0C 


Module Body 


CRC Check Value 


$0D Mode Byte - (D S PE PW PRE W R) 
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OS-9 Interaction With Devices 


Device drivers often must wait for hardware to complete a task 
or for a user to enter data. Such a wait situation occurs if an 
SCF device driver receives a Read but there is no data is avail- 
able, or if it receives a Write and no buffer space is available. 
OS-9 drivers that encounter this situation should suspend the 
current process (via F$Sleep). In this way the driver allows other 
processes to continue using CPU time. 


The most efficient way for a driver to awaken itself and resume 
processing data is by using interrupt requests (IRQs). It is possi- 
ble for the driver to sleep for a number of system clock ticks and 
then check the device or buffer for a ready signal. The drawbacks 
to this technique are: 


e@ It requires the system clock to always remain active. 


@ It might require a large number of ticks (perhaps 20) for 
the device to become ready. Such a case leaves you with 
a dilemma. If you make the program sleep for two ticks, 
the system wastes CPU time while checking for device 
ready. If the driver sleeps 20 ticks, it does not have a 
good response time. 


An interrupt system allows the hardware to report to the CPU 
and the device drivers when the device is finished with an opera- 
tion. Using interrupts to its advantage, a device driver can set 
up interrupt handling to occur when a character is sent or 
received or when a disk operation is complete. There is a built-in 
polling facility for pausing and awakening processes. Here is a 
technique for handling interrupts in a device driver: 


1. Use the Init routine to place the driver interrupt service call 
(IRQSVC) routine in the IRQ polling sequence via an F$IRQ 
system call: 


Idd V.Port,u get address to poll 
leax IRGPOLL,per point to IRQ packet 
leay IRQSVC,pcr point to IRQ@ routine 
OS9 FS$IRQ add dev to poll sequence 
bes Error abnormal exit if error 


2. Ensure that driver programs waiting for their hardware, call 
the sleep routine. The sleep routine copies V.Busy to 
V.Wake. Then, it goes to sleep for some period of time. 
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3. When the driver program wakes up, have it check to see 
whether it was awakened by an interrupt or by a signal sent 
from some other process. 


Usually, the driver performs this check by reading the Ww 
V.Wake storage byte. The V.Busy byte is maintained by the 

file manager to be used as the process ID of the process 

using the driver. When V.Busy is copied into V.Wake, then 
V.Wake becomes a flag byte and an information byte. A non- 

zero Wake byte indicates that there is a process awaiting an 
interrupt. The value in the Wake byte indicates the process 

to be awakened by sending a wakeup signal as shown in the 
following code: 


Ida V.Busy,u get proc ID 

sta V.Wake,u arrange for wakeup 

andce #*IntMasks prep tor interrupts 

JLeeped Lax: #0 or any other tick time 

Cit signal test. 

Us? FSsleep await an IRQ 

ldx D.Proc geal proc dese ptr if 
signal test 

ldb- PeSignal>x is signal present? WwW 
Cit Signal test? 

pine Siglest Pe it 80 2 Signed 
test 

tst V.Wake,u LRG occur’? 

bre Sleepsv bra if not 


Note that the code labeled “if signal test” is only necessary 
if the driver wishes to return to the caller if a signal is sent 
without waiting for the device to finish. Also note that IRQs 
and FIRQs must be masked between the time a command is 
given to the device and the moving of V.Busy and V.Wake. If 
they are not masked, it is possible for the device IRQ to 
occur and the IRQSVC routine to become confused as to 
whether it is sending a wakeup signal or not. 


4-12 


OS-9’s Unified Input/Output System / 4 


When the device issues an interrupt, OS-9 calls the routine 
at the address given in F$IRQ with the interrupts masked. 
Make the routine as short as possible, and have it return 
with an RTS instruction. IRQSVC can verify that an inter- 
rupt has occurred for the device. It needs to clear the inter- 
rupt to retrieve any data in the device. Then the V.Wake 
byte communicates with the main driver module. If V.Wake 
is non-zero, clear it to indicate a true device interrupt and 
use its contents as the process ID for an F$Send system call. 
The F$Send call sends a wakeup signal to the process. Here 
is an example: 


Idx V.Port,u get device address 

Lat 7? is if real interrupt from device’? 
bne IRQSVC90 bra to error if not 

Ida Data,x get data from device 

sta 0,y 

lda V.Wake,u 

beq IRQSVC80 bra if none 

clr V.Wake,u clear it as flag to main 
routine 

ldb #S¢Wake,u get wakeup signal 

OS9 F$Send send signal to driver 


IRQSVC80 clrb clear carry bit Call is well) 


rts 


IRQSVC90 comb set carry bit Cis an IRQ call) 


rts 


Suspend State (Level Two only) 


The Suspend State allows the elimination of the F$Send system 
call during interrupt handling. Because the process is already in 
the active queue, it need not be moved from one queue to 
another. The device driver IRQSVC routine can now wake up the 
suspended main driver by clearing the process status byte sus- 
pend bit in the process state. Following are sample routines for 
the Sleep and IRQSVC calls: 


lda D.Proc Get process ptr 
sta V.Wake,u prep for re-awakening 


enable device to IRQ, give command, etc. 
bra Cmd50 enter suspend loop 


Cmd30 ldx D.Proc get ptr to process desc 
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lda P$State,x get state flag 
ora #Suspend put proc in suspend state 
sta P$State,x save it in proc desc 
andcc #*IntMasks unmask interrupts 
Idx #1 give ue time: slice 
O0S9 F$Sleep suspend Cin active queue) 
CmdS0 orce #IntMasks mask interrupts while 
changing state 
ldx D.Proc get proc desc addr Cif signal 
test) 
Ilda P$Signal,x get signal Cif signal test) 
beq SigProc tre if signal to be handled 
lda V.Wake,u true interrupt? 
bne Cmd30 bra if not 
andce #*IntMasks assure interrupts unmasked 


Note that D.Proc is a pointer to the process descriptor of the cur- 
rent process. Process descriptors are always allocated on 256- 
byte page boundaries. Thus, having the high order byte of the 
address is adequate to locate the descriptor. D.Proc is put in 
V.Wake as a dual value. In one instance, it is a flag byte indi- 
cating that a process is indeed suspended. In the other instance, 
it is a pointer to the process descriptor which enables the 
IRQSVC routine to clear the suspend bit. It is necessary to have 
the interrupts masked from the time the device is enabled until 
the suspend bit has been set. Making the interrupts ensure that 
the IRQSVC routine does not think it has cleared the suspend 
bit before it is even set. If this happens, when the bit is set the 
process might go into permanent suspension. The IRQSVC rou- 
tine sample follows: 


Idy V.Port,u get dev addr 

tst V.Wake,u is process awaiting 
IRQ? 

beg IRQSVCER no exit 


clear device interrupt 
exit if IRQ not from this device 


Ilda V.Wake,u get process ptr 

clrb 

stb V.Wake,u clear proc waiting FLAG 
Lin -d,% get process descriptor ptr 
Ida P$State,x get state flag 

anda # Suspend clear suspend state 
sta P$State,x save it 


a 
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clrb clear carry bit 
rts 

IRQSVCER comb set carry Bit 
rts 


Device Descriptor Modules 


Device descriptor modules are small, non-executable modules. 
Each one provides information that associates a specific I/O 
device with its logical name, hardware controller address(es), 
device driver, file manager name, and initialization parameters. 


Unlike the device drivers and file managers, which operate on 
classes of devices, each device descriptor tailors its functions to a 
specific device. Each device must have a device descriptor. 


Device descriptor modules use a standard module header, in 
which the module type is specified as code $Fx (device descrip- 
tor). The name of the module is the name by which the system 
and user know the device (the device name given in pathlists). 


The rest of the device descriptor header consists of the informa- 
tion in the following chart: 


Relative 

Address(es) Use 

$09,$0A The relative address of the file manager 
name string address 

$0B,$0C The relative address of the device driver 
name string 

$0D Mode/Capabilities: D S PE PW PRE WR 
(directory, single user, public execute, pub- 
lic write, public read, execute, write, read) 

$0E,$0F,$10 The absolute physical (24-bit) address of the 
device controller 

$11 The number of bytes (n bytes) in the ini- 
tialization table 

$12,$12+n Initialization table 


When OS-9 opens a path to the device, the system copies the ini- 
tialization table into the option section (PD.OPT) of the path 
descriptor. (See “Path Descriptors” in this chapter.) 
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The values in this table can be used to define the operating 
parameters that are alterable by the Get Status and Set Status 
system calls (I$GetStt and I$SetStt). For example, parameters 
that are used when initializing terminals define which control 
characters are to be used for functions such as backspace and 
delete. 


The initialization table can be a maximum of 32 bytes long. If 
the table is fewer than 32 bytes long, OS-9 sets the remaining 
values in the path descriptor to 0. 


You might wish to add devices to your system. If a similar device 
driver already exists, all you need to do is add the new hardware 
and load another device descriptor. Device descriptors can be in 
the boot module or they can be loaded into RAM from mass-stor- 
age files while the system is running. 


The following diagram illustrates the device descriptor format: 
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Relative 
Address 


$00 
$01 
$02 
$03 
$04 
$05 
$06 
$07 
$08 
$09 


$0A 
$0B 


$0D 
$0E 


$0F 
$10 


$11 
$12,$12+n 


Device Descriptor Format 


Use 


Sync Bytes ($87,$CD) 


Module Size (bytes) 


Offset to Module Name 


F$ (Type) $1 (Lang) 


Header Parity Check 


Offset to File Manager 
Name String 


Offset to Device Driver 
Name String 


Mode Byte 


Device Controller 
Absolute Physical Addr. 
(24 bit) 


Initialization Table Size 


(Initialization Table) 


(Name Strings, and so on) 


CRC Check Value 


a 


Check 


=) 
$9 
a 
© 


header 
parity 
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module 


CRC 
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Path Descriptors 


Every open path is represented by a data structure called a path 
descriptor (PD). The PD contains the information the file man- 
agers and device drivers require to perform I/O functions. 


PDs are 64 bytes long and are dynamically allocated and deallo- 
cated by the I/O manager as paths are opened and closed. 


They are internal data structures, that are not normally refer- 
enced from user or applications programs. The description of PDs 
is presented here mainly for those programmers who need to 
write custom file managers, device drivers, or other extensions to 
OS-9. 


PDs have three sections. The first section, which is ten bytes 
long, is the same for all file managers and device drivers. The 
information in the first section is shown in the following chart. 


Path Descriptor: Standard Information 


Relative Size 
Name Address (Bytes) Use 


PD.PD $00 1 Path number 

PD.MOD $01 i! Access mode: 1 = read, 2 = 
write, 3 = update 

PD.CNT $02 i Number of open paths using 
this PD 

PD.DEV $03 2 Address of the associated 
device table entry 

PD.CPR $05 1 Current process ID 

PD.RGS $06 2 Address of the caller’s regis- 
ter stack 

PD.BUF $08 2 Address of the 256-byte 
data buffer (if used) 

PD.FST $0A 22 Defined by the file manager 

PD.OPT $20 32 Reserved for the Getstat/ 


Setstat options 


PD.FST is 22-byte storage reserved for and defined by each type 
of file manager for file pointers, permanent variables, and so on. 
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PD.OPT is a 32-byte option area used for file or device operat- 
ing parameters that are dynamically alterable. When the path is 
opened, the I/O manager initializes these variables by copying 
the initialization table that is in the device descriptor module. 
User programs can change the values later, using the Get Status 
and Set Status system calls. 


PD.FST and PD.OPT are defined for the file manager in the 
assembly-language equate file (SCFDefs for the SCF manager or 
RBFDefs for the RBF manager). 
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Random Block File Manager 


The random block file manager (RBF manager) supports disk 
storage. It is a re-entrant subroutine package called by the I/O 
manager for I/O system calls to random-access devices. It main- 
tains the logical and physical file structures. 


During normal operation, the RBF manager requests allocation 
and deallocation of 256-byte data buffers. Usually, one buffer is 
required for each open file. When physical I/O functions are nec- 
essary, the RBF manager directly calls the subroutines in the 
associated device drivers. All data transfers are performed using 
256-byte data blocks (pages). 


The RBF manager does not deal directly with physical addresses 
such as tracks and cylinders. Instead, it passes to the device 
drivers address parameters, using a standard address called a 
logical sector number, or LSN. LSNs are integers from 0 to n-1, 
where n is the maximum number of sectors on the media. The 
driver translates the logical sector number to actual cylinder/ 
track/sector values. 


Because the RBF manager supports many devices that have dif- 
ferent performance and storage capacities, it is highly parame- 
ter-driven. The physical parameters it uses are stored on the 
media itself. 


On disk systems, the parameters are written on the first few 
sectors of Track 0. The device drivers also use the information, 
particularly the physical parameters stored on Sector 0. These 
parameters are written by the FORMAT program that initial- 
izes and tests the disk. 


Logical and Physical Disk Organization 


All disks used by OS-9 store basic identification, file structure, 
and storage allocation information on these first few sectors. 


LSN 0 is the identification sector. LSN 1 is the disk allocation 
map sector. LSN 2 marks the beginning of the disk’s ROOT 
directory. The following section tells more about LSN 0 and LSN 
ds 
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Identification Sector (LSN 0) 


LSN 0 contains a description of the physical and logical charac- 
teristics of the disk. These characteristics are set by the FOR- 
MAT command program when the disk is initialized. 


The following table gives the OS-9 mnemonic name, byte 
address, size, and description of each value stored in this LSN 0. 


Name 
DD.TOT 


DD.TKS 
DD.MAP 


DD.BIT 
DD.DIR 


DD.OWN 
DD.ATT 
DD.DSK 


DD.FMT 


DD.SPT 
DD.RES 
DD.BT 


DD.BSZ 


DD.DAT 
DD.NAM 


DD.OPT 
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Relative Size 
Address (Bytes) 


$00 


32 


Use 
Number of sectors on disk 


Track size (in sectors) 


Number of bytes in the alloca- 
tion bit map 


Number of sectors per cluster 


Starting sector of the ROOT 
directory 


Owner’s user number 
Disk attributes 


Disk identification (for internal 
use) 


Disk format, density, number 
of sides 


Number of sectors per track 
Reserved for future use 


Starting sector of the boot- 
strap file 


Size of the bootstrap file (in 
bytes) 


Time of creation (Y:M:D:H:M) 


Volume name in which the last 
character has the most signifi- 
cant bit set 


Path descriptor options 
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Disk Allocation Map Sector (LSN 1) 


LSN 1 contains the disk allocation map, which is created by 
FORMAT. This map shows which sectors are allocated to the 
files and which are free for future use. 


Each bit in the allocation map represents a sector or cluster of 
sectors on the disk. If the bit is set, the sector is considered to be 
in use, defective, or non-existent. If the bit is cleared, the corre- 
sponding cluster is available. The allocation map usually starts 
at LSN1. The number of sectors it requires varies according to 
how many bits are needed for the map. DD.MAP specifies the 
actual number of bytes used in the map. 


Multiple sector allocation maps allow the number of sectors/clus- 
ter to be as small as possible for high volume media. 


The FORMAT utility bases the size of the allocation map on the 
size and number of sectors per cluster. 


The DD.MAP value in LSN 0 specifies the number of bytes (in 
LSN 1) that are used in the map. 


Each bit on the disk allocation map corresponds to one sector 
cluster on the disk. The DD.BIT value in LSN 0 specifies the 
number of sectors per cluster. The number is an integral power 
of 2 (1, 2, 4, 8, 16, and so on). 


If a cluster is available, the corresponding bit is cleared. If it is 
allocated, non-existent, or physically defective, the corresponding 
bit is set. 


ROOT Directory 


This file is the parent directory of all other files and directories 
on the disk. It is the directory accessed using the physical device 
name (such as /D1). Usually, it immediately follows the Alloca- 
tion Map. The location of the ROOT directory file descriptor is 
specified in DD.DIR. The ROOT directory contains an entry for 
each file that resides in the directory, including other 
directories. 


File Descriptor Sector 


The first sector of every file is the file descriptor. It contains the 
logical and physical description of the file. 
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The following table describes the contents of the file descriptor. 


Relative Size 


Name Address (Bytes) Use 

FD.ATT $00 1 File attributes: DS PE PW PR 
E W R (see next chart) 

FD.OWN ~ $01 Z Owner’s user ID 

FD.DAT $03 5 a last modified: (Y M D H 

FD.LNK $08 1 Link count 

FD.SIZ $09 4 File size (number of bytes) 

FD.CREAT $0D 3 Date created (Y M D) 

FD.SEG $10 240 Segment list (see next chart) 


FD.ATT. (The attribute byte) contains the file permission bits. 
When set the bits indicate the following: 


Bit 7 Directory 

Bit 6 Single user 
Bit 5 Public execute 
Bit 4 Public write 
Bit 3 Public read 
Bit 2 Execute 

Bit 1 Write 

Bit 0 Read 


FD.SEG (the segment list) consists of a maximum of 48 5-byte 
entries that have the size and address of each file block in logical 
order. Each entry has the block’s 3-byte LSN and 2-byte size (in 
sectors). The entry following the last segment is zero. 


After creation, a file has no data segments allocated to it until 
the first write. (Write operations past the current end-of-file 
cause sectors to be added to the file. The first write is always 
past the end-of-file.) 


If the file has no segments, it is given an initial segment. Usu- 
ally, this segment has the number of sectors specified by the 
minimum allocation entry in the device descriptor. If, however, 
the number of sectors requested is more than the minimum, the 
initial segment has the requested number. 
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Later expansions of the file usually are also made in minimum 
allocation increments. Whenever possible, OS-9 expands the last 
segment, instead of adding a segment. When the file is closed, 
OS-9 truncates unused sectors in the last segment. 


OS-9 tries to minimize the number of storage segments used in 
a file. In fact, many files have only one segment. In such cases, 
no extra Read operations are needed to randomly access any byte 
in the file. 


If a file is repeatedly closed, opened, and expanded, it can 
become fragmented so that it has many segments. You can avoid 
this fragmentation by writing a byte at the highest address you 
want to be used on a file. Do this before writing any other data. 


Directories 


Disk directories are files that have the D attribute set. A direc- 
tory contains an integral number of entries, each of which can 
hold the name and LSN of a file or another directory. 


Each directory entry contains 29 bytes for the filename, followed 
by the three bytes for the LSN of the file’s descriptor sector. The 
filename is left-justified in the field, with the most significant bit 
of the last character set. Unused entries have a zero byte in the 
first filename character position. 


Every disk has a master directory called the ROOT directory. 
The DD.DIR value in LSN 0 (identification sector) specifies the 
starting sector of the ROOT directory. 


The RBF Manager Definitions of the Path 
Descriptor 


As stated earlier in this chapter, the PD.FST section of the path 
descriptor is reserved for and defined by the file manager. The 
following table describes the use of this section by the RBF man- 
ager. For your convenience, it also includes the other sections of 
the PD. 
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Relative Size 


Name Address (Bytes) Use 
Universal Section (Same for all file managers and device drivers) 
PD.PD $00 1 Path number 
PD.MOD $01 1 Access mode 
1 = read, 
2 = write, 
3 = update 
PD.CNT $02 1 Number of open images (paths 
using this PD) 
PD.DEV $03 2 Address of the associated 
device table entry 
PD.CPR $05 1 Current process ID 
PD.RGS $06 2 Address of the caller’s 6809 
register stack 
PD.BUF $08 2 Address of the 256-byte data 


buffer (if used) 


Relative Size 


Name _— Address (Bytes) Use 
The RBF manager Path Descriptor Definitions (PD.FST Section) 
PD.SMF $0A 1 State flag: 
Bit 0 =current buffer is 
altered 
Bit 1 = current sector is in 
the buffer 


Bit 2 = descriptor sector is 
in the buffer 


PD.CP $0B 4 Current logical file position 
(byte address) 

PD.SIZ $S0F 4 File size 

PD.SBL $13 3 Segment beginning logical sec- 
tor number (LSN) 

PD.SBP $16 3 Segment beginning physical 


sector number (PSN) 
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Name 
PD.SSZ 


PD.DSK 
PD.DTB 


Name 
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Relative Size 
Address (Bytes) Use 


$19 3 Segment size 
$1C 2 Disk ID (for internal use only) 
$1K 2 Address of drive table 


Relative Size 
Address (Bytes) Use 


The RBF manager Option Section Definitions (PD.OPT Section) 


(Copied from the device descriptor) 


PD.DTP 


PD.DRV 
PDISTP 
PD.IYP 
PD.DNS 
PD.CYL 
PD.SID 

PD.VFY 
PD.SCT 


PD.TOS 


PD.ILV 
PD.SAS 
PD.TFM 


PD.EXTEN 


PD.STOFF 


$20 1 Device class: 
0 = SCF 
L:=> RBE 
2 = PIPE 
3 = SBF 
$21 i) Drive number (0..n) 
$22 1 Step rate 
$23 il Device type 
$24 1 Density capability 
$25 2 Number of cylinders (tracks) 
$27 i) Number of sides (surfaces) 
$28 1 0 = verify disk writes 
$29 y Default number of sectors per 
track 
$2B 2 Default number of sectors per 
track (Track 0) 
$2D 1 Sector interleave factor 
$2E 1 Segment allocation size 
$2F 1 DMA transfer mode 
$30 Z Path extension for record 
locking 
$32 1 Sector/track offsets 
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Relative Size 


Name Address (Bytes) Use 
(Not copied from the device descriptor): 
PD.ATT $33 1 File attributes 


(D S PE PW PRE W R) 
File descriptor PSN 
Directory file descriptor PSN 


PD.FD $34 
PD.DFD $37 
PD.DCP $3A 
PS.DVT $3E 


File’s directory entry pointer 


Address of the device table 
entry 


Do -& Wd 


Any values not determined by this table default to zero. 


RBF-Type Device Descriptor Modules 


This section describes the use of the initialization table con- 
tained in the device descriptor modules for RBF-type devices. 
The following values are those the I/O manager copies from the 
device descriptor to the path descriptor. 
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Relative Size 


Name Address (Bytes) Use 
$0-$11 Standard device descriptor 
module header 
IT.DTP $12 1 Device type: 
0 = SCF 
1 = RBF 
2 = PIPE 
3 = SBF 
IT.DRV $13 1 Drive number 
rrr $14 il Step rate 
LEY YP $15 i Device type (see RBF path 
descriptor) 
IT.DNS $16 ui Media density: 


Always 1 (double) 
(see following information) 


IT.CYL $17 Z Number of cylinders (tracks) 

IT.SID $19 | Number of sides 

IT. VFY $1A 1 0 = Verify disk writes 
1 = no verify 

IT.SCT $1B 2 Default number of sectors per 
track 

IT.TOS $1D 2 Default number of sectors per 
track (Track 0) 

IT. ILV $1F 1 Sector interleave factor 

IT.SAS $20 1 Minimum size of segment allo- 


cation (number of sectors to be 
allocated at one time) 


IT.DRV is used to associate a 1-byte integer with each drive 
that a controller handles. Number the drives for each controller 
as 0 to n-1, where n is the maximum number of drives the con- 
troller can handle. 


o-9 


OS-9 Technical Reference 


IT.TYP specifies the device type (all types). 


Bit 0 — 0 = 5-inch floppy diskette 

Bit 5 — 0 = Non-Color Computer format 
1 = Color Computer format 

Bit 6 — 0 = Standard OS-9 format 
1 = Non-standard format 

Bit 7 — 0 = Floppy diskette 
1 = Hard disk 


IT.DNS specifies the density capabilities (floppy diskette only). 


Bit 0 — 0 = Single-bit density (FM) 
1 = Double-bit density (MFM) 
Bit 1 — 0 = Single-track density (5-inch, 48 tracks per 
inch) 
1 = Double-track density (5-inch, 96 tracks per 
inch) 


IT.SAS specifies the minimum number of sectors allowed at one 
time. 


RBF Record Locking 


Record locking is a general term that refers to methods designed 
to preserve the integrity of files that can be accessed by more 
than one user or process. The OS-9 implementation of record 
locking is designed to be as invisible as possible. This means 
that existing programs do not have to be rewritten to take 
advantage of record locking facilities. You can usually write new 
programs without special concern for multi-user activity. 


Record locking involves detecting and preventing conflicts during 
record access. Whenever a process modifies a record, the system 
locks out other procedures from accessing the file. It defers 
access to other procedures until it is safe for them to write to the 
record. The system does not lock records during reads; so, multi- 
ple processes can read the record at the same time. 
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Record Locking and Unlocking 


To detect conflicts, OS-9 must recognize when a record is being 
updated. The RBF manager provides true record locking on a 
byte basis. A typical record update sequence is: 


OS9 I$Read Program reads record 
RECORD IS LOCKED 


Program updates record 


OS9 I$Seek reposition to record 
OS9 I$¢Write record is rewritten 
RECORD IS RELEASED 


When a file is opened in update mode, any read causes locking 
of the record being accessed. This happens because the RBF 
manager cannot determine in advance if the record is to be 
updated. The record stays locked out until the next read, write, 
or close. 


However, when a file is opened in the read or execute modes, the 
system does not lock accessed records because the records cannot 
be updated in these two modes. 


A subtle but important problem exists for programs that interro- 
gate a data base and occasionally update its data. If you neglect 
to release a record after accessing it, the record might be locked 
up indefinitely. This problem is characteristic of record locking 
systems and you can avoid it with careful programming. 


Only one portion of a file can be locked out at a time. If an 
application requires more than one record to be locked out, open 
multiple paths to the same file and lock the record accessed by 
each path. RBF notices that the same process owns both paths 
and keeps them from locking each other out. 
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Non-Shareable Files 


Sometimes (although rarely), you must create a file that can 
never be accessed by more than one user at a time. To lock the 
file, you set the single-user (s) bit in the file’s attribute byte. You 
can do this by using the proper option when the file is created, 
or later using the OS-9 ATTR command. Once the single-user 
bit is set, only one user can open the file at a time. If other users 
attempt to open the file, Error 253 is returned. Note however, 
that non-shareable means only one path can be opened to a file 
at one time. Do not allow two processes to concurrently access a 
non-shareable file through the same path. 


More commonly, you need to declare a file as single-user only 
during the execution of a specific program. You can do this by 
opening the file with the single-user bit set. For example, sup- 
pose a process is sorting a file. With the file’s single-user bit set, 
OS-9 treats the file exactly as though it had a single-user attrib- 
ute. If another process attempts to open the file, OS-9 returns 
Error 253. 


You can duplicate non-shareable paths by using the I$Dup sys- 
tem call. This means that it can be inherited, and therefore 
accessible to more than one process at a time. Single-user means 
that the file can be opened only once. 


End-of-File Lock 


A special case of record locking occurs when a user reads or 
writes data at the end of a file, creating an HOF Lock. An EOF 
Lock keeps the end of the file locked out until a process performs 
a READ or WRITE that is not at the end of the file. It prevents 
problems that might otherwise occur when two users want to 
simultaneously extend a file. The EOF Lock is the only case in 
which a WRITE call automatically causes portions of a file to be 
locked out. An interesting and useful side effect of the EOF Lock 
function occurs if a program creates a file for sequential output. 
As soon as the program creates the file, EOF Lock is set and no 
other process can pass the writer in processing the file. For 
example, if an assembler redirects a listing to a disk file, and a 
spooler utility tries to print a line from the file before it is writ- 
ten, record locking makes the spooler wait and stay at least one 
step behind the assembler. 
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Deadlock Detection 


A deadly embrace, or deadlock, typically occurs when two pro- 
cesses attempt to gain control of two or more disk areas at the 
same time. If each process gets one area (locking out the other 
process), both processes become permanently stuck. Each waits 
for a segment that can never become free. This situation is not 
restricted to any particular record locking scheme or operating 
system. 


When a deadly embrace occurs, RBF returns a deadlock error 
(Error 254) to the process that caused OS-9 to detect the dead- 
lock. To avoid deadlocks, make sure that processes always access 
records of shared files in the same sequence. 


When a deadlock error occurs, it is not sufficient for a program 
to retry the operation that caused the error. If all processes use 
this strategy, none can ever succeed. For any process to proceed, 
at least one must cancel operation to release its control over a 
requesting segment. 


RBF-Type Device Driver Modules 


An RBF-type device driver module contains a package of subrou- 
tines that perform sector-oriented I/O to or from a specific hard- 
ware controller. Such a module is usually re-entrant. Because of 
this, one copy of one device driver module can simultaneously 
run several devices that use identical I/O controllers. 


The I/O manager allocates a permanent memory area for each 
device driver. The size of the memory area is given in the device 
driver module header. The I/O manager and the RBF manager 
use some of this area. The device driver can use the rest in any 
manner. This area is used as follows: 


The RBF Device Memory Area Definitions 


Relative Size 


Name Address (Bytes) Use 

V.PAGE $00 il Port extended address bits 
A20-A16 

V.PORT $01 2 Device base address (defined 


by the I/O manager) 
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Relative Size 


Name Address (Bytes) Use 

V.LPRC $03 1 ID of the last active process 
(not used by RBF device 
drivers) 

V.BUSY $04 if ID of the current process using 


driver (defined by RBF) 
0 = no current process 


V.WAKE ~ $05 1 ID of the process waiting for 
I/O completion (defined by the 
device driver) 


V.USER $06 0 Beginning of file manager spe- 
cific storage 
V.NDRV $06 1 Maximum number of drives 


the controller can use (defined 
by the device driver) 


$07 8 Reserved 
DRVBEG  $0F 0 Beginning of the drive tables 
TABLES $0F DRVMEN*N Space for number of tables 
reserved (7) 
FREE 0) Beginning of space available 
for driver 


These values are defined in files in the DEFS directory on the 
Development Package disk. 


TABLES. This area contains one table for each drive that the 
controller handles. (The RBF manager assumes that there are as 
many tables as indicated by V.NDRV.) Some time after the 
driver Init routine is called, the RBF manager issues a request 
for the driver to read LSN 0 from a drive table by copying the 
first part of LSN 0 (up to DD.SIZ) into the table. Following is 
the format of each drive table: 
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Relative Size 


Name Address (Bytes) Use 

DD.TOT $00 3 Number of sectors. 

DD.TKS $03 1 Track size (in sectors). 

DD.MAP $04 yi Number of bytes in the alloca- 
tion bit map. 

DD.BIT $06 2 Number of sectors per bit 
(cluster size). 

DD.DIR $08 3 Address (LSN) of the ROOT 
directory. 

DD.OWN ~~ $0B 2 Owner’s user number. 

DD.ATT $0D 1 Disk access attributes 
(D S PE PW PRE WR). 

DD.DSK SOE 2 Disk ID (a pseudo-random 
number used to detect diskette 
Swaps). 

DD.FMT $10 1 Media format. 

DD.SPT $11 vs Number of sectors per track. 


(Track 0 can use a different 
value specified by IT.TOS in 
the device descriptor.) 


DD.RES $13 2 Reserved for future use. 

DD.SIZ $15 0 Minimum size of device 
descriptor. 

V.TRAK $15 Py Number of the current track 


(the track that the head is on, 
and the track updated by the 
driver). 


V.BMB $17 1 Bit-map use flag: 
O = Bit map is not in use. 
(Disk driver routines 
must not alter V.BMB.) 


V.FILEHD $18 2 Open file list for this drive. 
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Relative Size 


Name Address (Bytes) Use 

V.DISKID $1A 2 Disk ID. 

V.BMAPSZ $1C 1 Size of bitmap. 

V.MAPSCT $1D 1 Lowest reasonable bitmap 
sector. 

V.RESBIT $1E 1 Reserved bitmap sector. 

V.SCTKOF $1F 1 Sector/track byte. 

V.SCOFST $20 1 Sector offset split from 
V.SCTKOF. 

V.TKOFST $21 1 Track offset split from 
V.SCTKOF. 

RESERVED $22 4 Reserved for future use. 

DRVMEN- $26 Size of each drive table. 


The format attributes (DD.FMT) are these: 


Bit BO = Number of sides 
0 = Single-sided 
1 = Double-sided 
Bit B1 = Density 
0 = Single-density 
1 = Double-density 
Bit B2 = Track density 
0 = Single (48 tracks per inch) 


1 = Double (96 tracks per inch) 


RBF Device Driver Subroutines 


Like all device driver modules, RBF device drivers use a stan- 
dard executable memory module format. 


The execution offset address in the module header points to a 
branch table that has six 3-byte entries. Each entry is typically 
a long branch (LBRA) to the corresponding subroutine. The 
branch table is defined as follows: 
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ENTRY LBRA 
LBRA 
LBRA 
LBRA 
LBRA 
LBRA 
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INIT 
READ 
WRITE 
GETSTA 
SETSTA 
TERM 


Initialize drive 
Read sector 
Write sector 

Get status 

Set status 
Terminate device 


Ensure that each subroutine exists with the C bit of the condi- 
tion code register cleared if no error occurred. If an error occurs, 
set the C bit and return an appropriate error code Register B. 


The rest of this chapter describes the RBF device driver subrou- 
tines and their entry and exit conditions. 
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Init Ititializes a device and the device’s memory 
area. 


Entry Conditions: 


Y = address of the device descriptor 
U = address of the device memory area 


Exit Conditions: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e If you want OS-9 to verify disk writes, use the Request 
Memory system call (F$SRqMem) to allocate a 256-byte 
buffer area in which a sector can be read back and verified 
after a write. 


@ You must initialize the device memory area. For floppy 
diskette controllers, initialization typically consists of: 


1. Initializing V.NDRV to the number of drives with which 
the controller works 


2. Initializing DD.TOT (in the drive table) to a non-zero 
value so that Sector 0 can be read or written 


3. Initializing V.TRAK to $FF so that the first seek finds 
Track 0 


4. Placing the IRQ service routine on the IRQ polling list, 
using the Set IRQ system call (F$IRQ) 


5. Initializing the device control registers (enabling inter- 
rupts if necessary) 


e@ Prior to being called, the device memory area is cleared (set 
to zero), except for V.PAGE and V.PORT. (These areas con- 
tain the 24- bit device address.) Ensure the driver initial- 
izes each drive table appropriately for the type of diskette 
that the driver expects to be used on the corresponding 
drive. 
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Read Reads a 256-byte sector from a disk and 
places it in a 256-byte sector buffer. 


Entry Conditions: 


B = MSB of the disk’s LSN 

X = LSB of the disk’s LSN 

Y = address of the path descriptor 

U = address of the device memory area 


Exit Conditions: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 
@ The following is a typical routine for using Read: 


1. Get the sector buffer address from PD.BUF in the path 
descriptor. 


2. Get the drive number from PD.DRV in the path 
descriptor. 


3. Compute the physical disk address from the logical sec- 
tor number. 


4. Initiate the Read operation. 


5. Copy V.BUSY to V.WAKE. The driver goes to sleep and 
waits for the I/O to complete. (The IRQ service routine is 
responsible for sending a wakeup signal.) After awaken- 
ing, the driver tests V.WAKE to see if it is clear. If it 
isn’t clear, the driver goes back to sleep. 


@ Whenever you read LSN 0, you must copy the first part of 
this sector into the proper drive table. (Get the drive num- 
ber from PD.DRV in the path descriptor.) The number of 
bytes to copy is in DD.SIZ. Use the drive number (PD.DRV) 
to compute the offset for the corresponding drive table as 
follows: | 
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LDA PD.DRV,Y Get the drive number 

LDB #DRVMEN Get the size of a 
drive table 

MUL 

LEAX DRVBEG,U Get the address of 
the first table 

LE Ae.” shy oe Compute the address 
of the table 
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Write writes a 256-byte sector buffer to a disk. 


Entry Conditions: 


B = MSB of the disk LSN 

X  =LSB of the disk LSN 

Y = address of the path descriptor 

U = address of the device memory area 


Exit Conditions: 


CC =carry set on error 
B = error code 


Additional Information: 
@ Following is a typical routine for using Write: 


1. Get the sector buffer address from PD.BUF in the path 
descriptor. 


2. Get the drive number from PD.DRV in the path descriptor. 


3. Compute the physical disk address from the logical sector 
number. 


4. Initiate the Write operation. 


5. Copy V.BUSY to V.WAKE. The driver then goes to sleep 
and waits for the I/O to complete. (The IRQ service routine 
sends the wakeup signal.) After awakening, the driver tests 
V.WAKE to see if it is clear. If it is not, the driver goes 
back to sleep. If the disk controller cannot be interrupt-dri- 
ven, it is necessary to perform a programmed I/O transfer. 


6. If PF.VFY in the path descriptor is equal to zero, read the 
sector back in and verify that it is written correctly. Verifi- 
cation usually does not involve a comparison of all of the 
data bytes. 


e If disk writes are to be verified, the Init routine must 
request the buffer in which to place the sector when it is 
read back. Do not copy LSN 0 into the drive table when 
reading it back for verification. 
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@ Use the drive number (PD.DRV) to compute the offset to 
the corresponding drive table as shown for the Read 
routine. 
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Getstats and Setstats 


Reads or changes device’s operating parameters. 


Entry Conditions: 


U = address of the device memory area 
Y = address of the path descriptor 
A = status code 


Exit Conditions: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ Get/set the device’s operating parameters (status) as speci- 
fied for the Get Status and Set Status system calls. Getsta 
and Setsta are wild card calls. 


@ It might be necessary to examine or change the register 
stack that contains the values of the 6809 register at the 
time of the call. The address of the register stack is in 
PD.RGS, which is located in the path descriptor. You can 
use the following offsets to access any value in the register 


stack: 
Relative 

Reg. Addr. Size 6809 Reg. 
R$CC $00 i) Condition Code Reg. 
R$D $01 2 Register D 
R$A $01 if Register A 
R$B $02 1 Register B 
RSDP $03 1 Register DP 
R$X $04 2 Register X 
RSY $06 2 Register Y 
R$U $08 Z Register U 
R$PC $0A 2 Program Counter 


@ Register D overlays Registers A and B. 
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Term Terminate a device. 


Entry Conditions: 
U = address of the device memory area 


Exit Conditions: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ This routine is called when a device is no longer in use in 
the system (when the link count of its device descriptor 
module becomes zero). 


@ Following is a typical routine for using Term: 
1. Wait until any pending I/O is completed. 
2. Disable the device interrupts. 
3. Remove the device from the IRQ polling list. 
4 


. If the Init routine reserved a 256-byte buffer for verify- 
ing disk writes, return the memory with the Return 
Sysmem system call (F$SRtMem). 
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IRQ Service Routine 


Services device interrupts. 


Additional Information: 


@ The IRQ Service routine sends a wakeup signal to the pro- 
cess indicated by the process ID in V.WAKE when the I/O 
is complete. It then clears V.WAKE as a flag to indicate to 
the main program that the IRQ has indeed occurred. 


@ When the IRQ service routine finishes servicing an inter- 
rupt it must clear the carry and exit with an RTS 
instruction. 


e@ Although this routine is not included in the device driver 
module branch table and is not called directly by the RBF 
manager, it is a key routine in interrupt-driven drivers. Its 
function is to: 


1. Service the device interrupts (receive data from device or 
send data to it). The IRQ service routine puts its data 
into and get its data from buffers that are defined in the 
device memory area. 


2. Wake up a process that is waiting for I/O to be com- 
pleted. To do this, the routine checks to see if there is a 
process ID in V.WAKE (if the bit is non-zero); if so, it 
sends a wakeup signal to that process. 


3. If the device is ready to send more data, and the output 
buffer is empty, disable the device’s ready to transmit 
interrupts. 
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Boot (Bootstrap Module) 


Loads the boot file into 


Entry Conditions: 


None 


Exit Conditions: 


D- = size of the boot file (in bytes) 

X = address at which the boot file was loaded into memory 
CC =carry set on error 

B = error code (if any) 


Additional Information: 


@ The Boot module is not part of the disk driver. It is a sepa- 
rate module that is stored on the boot track of the system 
disk with OS9P1 and REL. 


e The bootstrap module contains one subroutine that loads 
the bootstrap file and related information into memory. It 
uses the standard executable module format with a module 
type of $C. The execution offset in the module header con- 
tains the offset to the entry point of this subroutine. 


@ The module gets the starting sector number and size of the 
OS9Boot file from LSN 0. OS-9 allocates a memory area 
large enough for the Boot file. Then, it loads the Boot file 
into this memory area. 


@ Following is a typical routine for using Boot: 


1. Read LSN 0 from the disk into a buffer area. The Boot 
module must pick its own buffer area. LSN 0 contains 
the values for DD.BT (the 24-bit LSN of the bootstrap 
file), and DD.BSZ (the size of the bootstrap file in bytes). 


2. Get the 24-bit LSN of the bootstrap file from DD.BT. 


3. Get the size of the bootstrap file from DD.BSZ. The Boot 
module is contained in one logically contiguous block 
beginning at the logical sector specified in DD.BT and 
extending for DD.BSZ/256 +1 sectors. 
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4. Use the OS-9 Request Sysmem system call (F$SRqMem) 
to request the memory area in which the Boot file is 
loaded. 


5. Read the Boot file into this memory area. 


6. Return the size of the Boot file and its location. Boot file 
is loaded. 
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Sequential Character 
File Manager 


The Sequential Character File Manager (SCF) supports devices 
that operate on a character-by-character basis. These include 
terminals, printers, and modems. 


SCF is a re-entrant subroutine package. The I/O manager calls 
the SCF manager for I/O system handling of sequential, charac- 
ter-oriented devices. The SCF manager includes the extensive I/O 
editing functions typical of line-oriented operation, such as: 


@ backspace 

@ line delete 

® line repeat 

@ auto line feed 

® screen pause 

@ return delay padding 


The SCF-type device driver modules are CC3IO, PRINTER, and 
RS-232. They run the video display, printer, and serial ports 
respectively. See the OS-9 Commands manual for additional 
Color Computer I/O devices. 


SCF Line Editing Functions 


The SCF manager supports two sets of read and write functions. 
I$Read and I$Write pass data with no modification. I$ReadLn 
and I$WritLn provide full line editing of device functions. 


Read and Write 


The Read and Write system calls to SCF-type devices correspond 
to the BASICO9 GET and PUT statements. While they perform 
little modification to the data they pass, they do filter out key- 
board interrupt, keyboard terminate, and pause character. (Edit- 
ing is disabled if the corresponding character in the path 
descriptor contains a zero.) 
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Carriage returns are not followed by line feeds or nulls automat- 
ically, and the high order bits are passed as sent/received. 


Read Line and Write Line 


The Read Line and Write Line system calls to SCF-type devices 
correspond to the BASICO9 INPUT, PRINT, READ, and WRITE 
statements. They provide full line editing of all functions enabled 
for a particular device. 


The system initializes I$ReadLn and I$WritLn functions when 
you first use a particular device. (OS-9 copies the option table 
from the device descriptor table associated with the specific 
device. ) 


Later, you can alter the calls—either from assembly-language 
programs (using the Get Status system call), or from the key- 
board (using the TMODE command). All bytes transferred by 
Readln and Writln have the high order bit cleared. 


SCF Definitions of the Path Descriptor 


The PD.FST and PD.OPT sections of the path descriptor are 
reserved for and used by the SCF file manager. 


The following table describes the SCF manager’s use of PD.FST 
and PD.OPT. For your convenience, the table also includes the 
other sections of the PD. 


The PD.OPT section contains the values that determine the line 
editing functions. It contains many device operating parameters 
that can be read or written by the Set Status or Get Status sys- 
tem call. Any values not set by this table default to zero. 


Note: You can disable most of the editing functions by set- 
ting the corresponding control character in the path 
descriptor to zero. You can use the Set Status system call 
or the TMODE command to do this. Or, you can go a step 
further by setting the corresponding control character value 
in the device descriptor module to zero. 


To determine the default settings for a specific device, you can 
inspect the device descriptor. 
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Relative Size 


Name Address (Bytes) Use 
ay Universal Section (Same for all file managers) 
PD.PD $00 | Path number 
PD.MOD $01 1 Access mode: 
1 = read 
2 = write 
3 = update 
PD.CNT $02 1 Number of open images (paths 
using this PD) 
PD.DEV $03 2 Address of the associated 
device table entry 
PD.CPR $05 i Current process ID 
PD.RGS $06 Z Address of the caller’s 6809 
register stack 
PD.BUF $08 2 Address of the 256-byte data 
co” buffer (if used) 
Relative Size 
Name Address (Bytes) Use 
SCF Path Descriptor Definitions (PD.FST Section) 
PD.DV2 $0A 2 Device table address of the sec- 
ond (echo) device 
PD.RAW $0C 1 Edit flag: 
0 = raw mode 
1 = edit mode 
PD.MAX $0D 2 Read Line maximum character 
count 
PD.MIN $0F 1 Devices are mine if cleared 
PD.STS $10 Status routine module address 
O PpDSTM $12 2 Reserved for status routine 
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Relative Size Use 
Name Address (Bytes) 


SCF Option Section Definition (PD.OPT Section) 
(Copied from the device descriptor) 


PD.DTP $20 1 Device class: 
0 = SCF 
i = RBE 
2 = PIPE 
o = SBE 
PD.UPC $21 i Case: 
QO = upper and lower 
1 = upper only 
PD.BSO $22 iL Backspace: 


0 = backspace 
1 = backspace, space and 
backspace 


PD.DLO $23 1 Delete: 
0 = backspace over line 
1 = carriage return, line 


feed 
PD.EKO $24 : Echo: 
0 = no echo 
PD.ALF S20 1 Auto line feed: 
0 = no auto line feed 
PD.NUL $26 1 End-of-line null count: 


n = number of nulls ($00) 
sent after each carriage 
return or carriage return 
and line feed (n = $00-$FF) 


PD.PAU $27 1 End of page pause: 

0 = no pause 
PD.PAG $28 1 Number of lines per page 
PD.BSP $29 1 Backspace character 
PD.DEL $2A 1 Delete-line character 
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Relative Size 
Name Address (Bytes) Use 


SCF Option Section Definition continued (PD.OPT Section) 
PD.EOR $2B 1 End-of-record character (End- 


of-line character) Read only. 
Normally set to $0D: 


0 = Terminate read-line 
only at the end of the 
file 

PD.EOF $2C 1 End-of-file character (read 
only) 

PD.RPR $2D 1 Reprint-line character 

PD.DUP $2E 1 Duplicate-last-line character 

PD.PSC $2F il Pause character 

PD.INT $30 1 Keyboard-interrupt character 

PD.QUT $31 1 Keyboard-terminate character 

PD.BSE $32 if Backspace-echo character 

PD.OVF $33 1 Line-overflow character (bell 
(CTRL }(G}) 

PD.PAR $34 i Device-initialization value 
(parity) 

PD.BAU $35 1 Software setable baud rate 

PD.D2P $36 2 Offset to second device name 
string 

PP.XON $38 1 ACIA XON char 

PD.XOFF $39 1 ACIA XOFF char 

PD.ERR $3A 1 Most recent I/O error status 

PD.TBL $3B 2 Copy of device table address 

PD.PLP $3D 2 Path descriptor list pointer 

PD.PST $3F 1 Current path status 
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PD.EOF specifies the end-of-file character. If this is the first 
and only character that is input to the SCF device, SCF returns 
an end-of-file error on Read or ReadIn. 


PD.PSC specifies the pause character, which suspends output to 
the device before the next end-of-record character. The pause 
character also deletes any type-ahead input for ReadIn. 


PD.INT specifies the keyboard-interrupt character. When the 
character is received, the system sends a keyboard terminate 
signal to the last user of a path. The character also terminates 
the current I/O request (if any) with an error identical to the 
keyboard interrupt signal code. 


PD.QUT specifies the keyboard-terminate character. When this 
character is received, the system sends a keyboard terminate 
signal to the last user of a path. The system also cancels the 
current I/O request (if any) by sending error code identical to the 
keyboard interrupt signal code. 


PD.PAR specifies the parity information for external serial 
devices. 


PD.BAU specifies baud rate, word length and stop bit informa- 
tion for serial devices. 


PD.XON contains either the character used to enable transmis- 
sion of characters or a null character that disables the use of 
XON. 


PD.XOFF contains either the character used to disable trans- 
mission of characters or a null character that disables the use of 
XOFF. 


SCF-Type Device Descriptor Modules 


The following chart shows how the initialization table in the 
device descriptors is used for SCF-type devices. The values are 
those the I/O manager copies from the device descriptor to the 
path descriptor. 


An SCF editing function is turned off if its corresponding value 
is set to zero. For example, if IT.EOF is set to zero, there is no 
end-of-file character. 
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Name 


(header) 


IT.DVC 


LELUPG 


IT.BSO 


IT.DLO 


IT.EKO 


IT.ALF 


IT.NUL 
IT.PAU 


IT.PAG 
IT.BSP 
IT.DEL 
IT.EOR 
IT. EOF 
PRP 
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Relative 


Size 


Address (Bytes) Use 


$00- 
11 


$12 


$13 


$14 


$15 


$16 


$17 


$18 
$19 


$1A 
$1B 
$1C 
$1D 
$1E 
$1F 


Se Be Se BS SS 


Standard device descriptor 
module header 


Device class: 


= S5CF 

lL =RBP 

2 = PIPE 

3 = SBE 
Case: 


= upper- and lowercase 
1 = uppercase only 


Backspace: 
0 = backspace 
1 = backspace, then space 
and backspace 


Delete: 
0 = backspace over line 
1 = carriage return 


Echo: 
0 = echo off 


Auto line feed: 
0 = auto line feed disabled 


End-of-line null count 
Pause: 

O = end-of-page pause 

disabled 

Number of lines per page 
Backspace character 
Delete-line character 
End-of-record character 


End-of-file character 


Reprint-line character 
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Relative Size 


Name Address (Bytes) Use 

IT.DUP $20 1 Duplicate-last-line character 

IT.PSC $21 1 Pause character 

IEINT $22 i Interrupt character 

IT.QUT $23 i Quit character 

IT.BSE $24 i Backspace echo character 

IT.OVF $25 1 Line-overflow character (bell) 

IT.PAR $26 1 Initialization value—used to 
initialize a device control reg- 
ister when a path is opened to 
it (parity) 

IT.BAU $27 | Baud rate 

IT. D2P $28 2 Attached device name string 
offset 

IT.XON $2A 1 X-ON character 

IT. XOFF $2B 1 X-OFF character 

IT.COL $2C 1 Number of columns for display 

IT.ROW $2D i) Number of rows for display 

IT.WND $2E 1 Window number 

IT. VAL $2F 1 Data in rest of descriptor is 
valid 

TESLyY $30 1 Window type 

IE.CPA $31 i! X cursor position 

tid WE Gs Sd $32 iL Y cursor position 

IT.FGC $33 1 Foreground color 

IT.BGC $34 1 Background color 

IT.BDC $35 1 Border color 


6-8 


Sequential Character File Manager / 6 


SCF-Type Device Driver Modules 


An SCF-type device driver module contains a package of subrou- 
tines that perform raw (unformatted) data I/O transfers to or 
from a specific hardware controller. Such a module is usually re- 
entrant so that one copy of the module can simultaneously run 
several devices that use identical I/O controllers. The 
I/O manager allocates a permanent memory area for each con- 
troller sharing the driver. 


The size of the memory area is defined in the device driver mod- 
ule header. The I/O manager and SCF use some of the memory 
area. The device driver can use the rest in any way (typically as 
variables and buffers). Typically, the driver uses the area as 
follows: 


Relative Size 


Name Address (Bytes) Use 
V.PAGE $00 1 Port extended 24 bit address 
V.PORT $01 2 Device base address (defined 
by the I/O manager) 
V.LPRC $03 il ID of the last active process 
V.BUSY $04 1 ID of the active process 
(defined by RBF): 
O = no active process 
V.WAKE $05 1 ID of the process to reawaken 


after the device completes I/O 
(defined by the device driver): 
O = no waiting process 


V.USER $06 0 Beginning of file manager 
specific storage 
V.TYPE $06 1 Device type or parity 
V.LINE $07 1 Lines left until the end of the 
page 
V.PAUS $08 i! Pause request: 
O = no pause requested 
V.DEV2 $09 Z Attached device memory area 
V.INTR $0B i Interrupt character 
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Relative Size 


Name Address (Bytes) Use 

V.QUIT $0C 1 Quit character 

V.PCHR $0D 1 Pause character 

V.ERR $0E 1 Error accumulator 

V.XON $0F : XON character 

V.XOFF $10 1 XOFF character 

V. KANJI $11 1 Reserved 

V.KBUF $12 2 Reserved 

V.MODADR $14 2 Reserved 

V.PDLHD $16 2 Path descriptor list header 

V.RSV $18 5 Reserved 

V.SCF $1D 0 End of SCF memory 
requirements 

FREE $1D 0 Free for the device driver to 
use 


V.LPRC contains the process ID of the last process to use the 
device. The IRQ service routine sends this process the proper sig- 
nal if it receives a quit character or an interrupt character. 
V.LPRC is defined by SCF. 


V.BUSY contains the process ID of the process that is using the 
device. (If the device is not being used, V.BUSY contains a zero.) 
The process ID is used by SCF to prevent more than one process 
from using the device at the same time. V.BUSY is defined by 
SCF. 


SCF Device Driver Subroutines 


Like all device drivers, SCF device drivers use a standard exe- 
cutable memory module format. 


The execution offset address in the module header points to a 
branch table that has six 3-byte entries. Each entry is typically 
an LBRA to the corresponding subroutine. The branch table is 
defined as follows: 
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ENTRY LBRA INET Initialize driver 
LBRA READ Read character 
LBRA WRITE Write character 
LBRA GETSTA Get status 
LBRA SETSTA Set status 
LBRA TERM Terminate device 


If no error occurs, each subroutine exits with the C bit in the 
Condition Code Register cleared. If an error occurred, each sub- 
routine sets the C bit and returns an appropriate error code in 
Register B. 


The rest of this chapter describes these subroutines and their 
entry and exit conditions. 
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Init Initializes device control registers, and 
enables interrupts if necessary. 


Entry Conditions: 

Y = address of the device descriptor 

U = address of the device memory area 
Exit Conditions: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


e@ Prior to being called, the device memory area is cleared (set 
to zero), except for V.PAGE and V.PORT. (V.PAGE and 
V.PORT contain the device address.) There is no need to 
initialize the part of the memory area used by the I/O 
manager and SCF. 


@ Follow these steps to use Init: 
1. Initialize the device memory area. 


2. Place the IRQ service routine on the IRQ polling list, 
using the Set IRQ system call (F$IRQ). 


3. Initialize the device control registers. 
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Read _ Reads the next character from the input 
buffer. 


Entry Conditions: 


Y = = address of the path descriptor 
U = address of the device memory area 


Exit Conditions: 


A =character read 
CC =carry set on error 
B= error code (if any) 


Additional Information: 
@ This is a step by step description of a Read operation: 
1. Read gets the next character from the input buffer. 


2. If no data is ready, Read copies its process ID from 
V.BUSY into V.WAKE. It then uses the Sleep system 
call to put itself to sleep. 


3. Later, when Read receives data, the IRQ service rou- 
tine leaves the data in a buffer. Then, the routine 
checks V.WAKE to see if any process is waiting for the 
device to complete I/O. If so, the IRQ service routine 
sends a wakeup signal to the waiting process. 


e@ Data buffers are not automatically allocated. If a buffer is 
used, it defines it in the device memory area. 
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Write sends a character (places a data byte in 
an output buffer) and enables the device 
output interrupts. 


Entry Conditions: 


A =character to write 
Y = address of the path descriptor 
U = _ = address of the device memory area 


Exit Conditions: 


CC 
B 


carry set on error 
error code (if any) 


Additional Information: 


e If the data buffer is full, Write copies its process ID from 
V.BUSY into V.WAKE. Write then puts itself to sleep. 


Later, when the IRQ service routine transmits a character 
and makes room for more data, it checks V.WAKE to see if 
there is a process waiting for the device to complete I/O. If 
there is, the routine sends a wakeup signal to that process. 


e Write must ensure that the IRQ service routine that starts 
it begins to place data in the buffer. After an interrupt is 
generated, the IRQ service routine continues to transmit 
data until the data buffer is empty. Then, it disables the 
device’s ready-to-transmit interrupts. 


@ Data buffers are not allocated automatically. If a buffer is 
used, define it in the device memory area. 
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Getsta and Setsta 


Gets/sets device operating parameters (status) as 
specified for the Get Status and Set Status system 
calls. Getsta and Setsta are wildcard calls. 


Entry Conditions: 


A _ = depends on the function code 
Y = address of the path descriptor 
U = address of the device memory area 


Other registers depend on the function code. 


Exit Conditions: 


B = error code (if any) 
CC =carry set on error 
Other registers depend on the function code 


Additional Information: 


@ Any codes not defined by the I/O manager or SCF are 
passed to the device driver. 


@ You might need to examine or change the register stack 
that contains the values of the 6809 registers at the time of 
the call. The address of the register stack can be found in 
PD.RGS, which is located in the path descriptor. 


@ You can use the following offsets to access any value in the 
register packet: 


Relative Size 
Name Address (Bytes) 6809 Register 
R$CC $00 1 Condition Codes Register 
R$D $01 0 Register D 
R$A $01 1 Register A 
R$B $02 1 Register B 
R$DP $03 il Register DP 
R$X $04 2 Register X 
R$Y $06 2 Register Y 
R$U $08 2 Register U 
R$PC $0A 2 Program Counter 


The function code is retrieved from the R$B on the user stack. 
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Term. Terminates a device. Term is called when a 
device is no longer in use (when the link 
count of the device descriptor module 
becomes zero). 


Entry Conditions: 


U = pointer to the device memory area 


Exit Conditions: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 
@ To use Term: 


1. Wait until the IRQ service routine empties the output 
buffer. 


2. Disable the device interrupts. 
3. Remove the device from the IRQ polling list. 


@ When Term closes the last path to a device, OS-9 returns 
to the memory pool the memory that the device used. If the 
device has been attached to the system using the I$Attach 
system call, OS-9 does not return the static storage for the 
driver until an I$Detach call is made to the device. Mod- 
ules contained in the Boot file are never terminated, even if 
their link counts reach 0. 
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IRQ Service Routine 


Receives device interrupts. When I/O is complete, the 
routine sends a wakeup signal to the process identi- 
fied by the process ID in V.WAKE. The routine also 
clears V.WAKE as a flag to indicate to the main pro- 
gram that the IRQ has occurred. 


Additional Information: 


@ The IRQ Service Routine is not included in device driver 
branch tables, and is not called directly by SCF. However, it 
is a key routine in device drivers. 


@ When the IRQ Service routine finishes servicing an inter- 
rupt, the routine must clear the carry and exit with an 
RTS instruction. 


@ Here is a typical sequence of events that the IRQ Service 
Routine performs: 


ki 


Service the device interrupts (receive data from the 
device or send data to it). Ensure this routine puts its 
data into and get its data from buffers that are defined 
in the device memory area. 


Wake up any process that is waiting for I/O to complete. 
To do this, the routine checks to see if there is a pro- 
cess ID in V.WAKE (a value other than zero); if so, it 
sends a wakeup signal to that process. 


If the device is ready to send more data, and the output 
buffer is empty, disable the device’s ready-to-transmit 
interrupts. 


If a pause character is received, set V.PAUS in the 
attached device storage area to a value other than zero. 
The address of the attached device memory area is in 
V.DEV2. 


V.PAUS in the attached device storage area to non-zero 
value. The address of the attached device memory area 
is in V.DEV2. 


If a keyboard terminate or interrupt character is 
received, signal the process in V.LPRC (last known 
process) if any. 
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The Pipe File Manager 
(PIPEMAN) 


The Pipe file manager handles control of processes that use 
paths to pipes. Pipes allow concurrently executing processes to 
send each other data by using the output of one process (the 
writer) as input to a second process (the reader). The reader gets 
input from the standard input. The exclamation point (!) opera- 
tor specifies that the input or output is from or to a pipe. The 
Pipe file manager allocates a 256-byte block and a path descrip- 
tor for data transfer. The Pipe file manager also determines 
which process has control of the pipe. The Pipe file manager has 
the standard file manager branch table at its entry point: 


PipeEnt l|bra Create 
Ibra Open 
lIbra MakDir 
Ibra ChgDir 
lbra Delete 
lbra Seek 
lbra PRead 
lbra PWrite 
lbra PRdLn 
lbra PWrLn 
lbra Getstat 
Ibra Putstat 
lbra Close 


You cannot use MakDir, ChgDir, Delete, and Seek with pipes. If 
you try to do so, the system returns ESUNKSVC (unknown ser- 
vice request). Getstat and Putstat are also no-action service rou- 
tines. They return without error. 


Create and Open perform the same functions. They set up the 
256-byte data exchange buffer, and save several addresses in the 
path descriptor. 


The Close request checks to see if any process is reading or writ- 
ing through the pipe. If not, OS-9 returns the buffer. 


PRead, PWrite, PRdLn, and PWrLn read data from the buffer 
and write data to it. 
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The ! operator tells the Shell that processes wish to communicate 
through a pipe. For example: 


preci 4 proce ENTER 


In this example, shell forks Procl with the standard output path 
to a pipe, and forks Proc2 with the Standard input path from a 


pipe. 
Shell can also handle a series of processes using pipes. Example: 
procl 1 proce *' prees. proc4 (ENTER | 


The following outline shows how to set up pipes between 
processes: 


Open /pipe save path in variable x 
Dup path #1 save stdout in variable y 
Dup x make path available 
Fork proct HUT pipe in Sidgeuat 
(Dup uses lowest available) 
Close #1 make path available 
Dup y restore stdout 
Close y make path available 
Dup path #9 save stdin in Y 
Close #9 make path available 
Dup x pul pipe in. stdin 
rork 2 Tork process < 
Close #9Q make path available 
Dup y restore stdin 
Close x no longer needed 
Close y no longer needed 
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Example: The following example shows how an application can 
initiate another process with the stdin and stdout routed 


through a pipe. 


Upen /pipel save 
pen ¥ pLpec save 
Dup @ save 
Dup 1 Save 
Close @ make 
Close 1 make 
Dup a make 
Dup 6b make 
Fork new process 


Close @ make 


Patt: 27 Vatianic a 
path in variable b 
stdin in variable x 
stdout in variable y 
path available 

path available 

pipet Stain 

pipee Stdout 


path available 


Close 1 make path available 

Dup x restore staan 

Dup y restore stdout 

Return aé&b return pipe path: numbers to caller 


Chapter 8 
System Calls 


System calls are used to communicate between the OS-9 operat- 
ing system and assembly-language programs. There are two 
major types of calls—I/O calls and function calls. 


Function calls include user mode calls and system mode calls. 


Each system call has a mnemonic name. Names of I/O calls start 
with I$. For example, the Change Directory call is I$ChgDir. 
Names of function calls start with F$. For example, the Allocate 
Bits call is F$Al]Bit. The names are defined in the assembler- 
input conditions equate file called OS9Defs. 


System mode calls are privileged. You can execute them only 
while OS-9 is in the system state (when it is processing another 
system call, executing a file manager or device driver, and so 
on). 


System mode calls are included in this manual primarily for pro- 
grammers writing device drivers and other system-level 
applications. 


Calling Procedure 


To execute any system calls, you need to use an SWI2 
instruction: 


1. Load the 6809 registers with any appropriate parameters. 


2. Execute an SWI2 instruction, followed immediately by a con- 
stant byte, which is the request code. In the references in 
this chapter, the first line is the system call name (for exam- 
ple Close Path) and the second line contains the call’s mne- 
monic name (for example [$Close), the software interrupt 
Code 2 (103F), and the call’s request code (for example, 8F) 
in hexadecimal. 


3. After OS-9 processes the call, it returns any parameters in 
the 6809 registers. If an error occurs, the C bit of the condi- 
tion code register is set, and Register B contains the appro- 
priate error code. This feature permits a BCS or BCC 
instruction immediately following the system call to branch 
either if there is an error or if no error occurs. 
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As an example, here is the Close system call: 


LDA PATHNUM 


SWIe2 
FCB $8F 
BCS ERROR 


You can use the assembler’s OS9 directive to simplify the call, as 
follows. 


LDA PATHNUM 
OSs I$¢Close 
BCS ERROR 


The ASM assembler allows any combination of upper- or lower- 
case letters. The RMA assembler, included in the OS-9 Level 
Two Development Pak, is case sensitive. The names in this man- 
ual have been spelled with upper and lower case letters, match- 
ing the defs for RMA. 


I/O System Calls 


OS-9’s I/O calls are easier to use than many other systems’ I/O 
calls. This is because the calling program does not have to allo- 
cate and set up file control blocks, sector buffers, and so on. 


Instead, OS-9 returns a 1-byte path number whenever a process 
opens a path to a file or device. Until the path is closed, you can 
use this path number in later I/O requests to identify the file or 
device. 


In addition, OS-9 allocates and maintains its own data struc- 
tures; so, you need not deal with them. 


System Call Descriptions 


The rest of this chapter consists of the system call descriptions. 
At the top of each description is the system call name, followed 
by its mnemonic name, the SWI2 code and the request code. 
Next are the call’s entry and exit conditions, followed by addi- 
tional information about the code where appropriate. 


In the system call descriptions, registers not specified as entry 
or exit conditions are not altered. Strings passed as parameters 
are normally terminated with a space character and end-of-line 
character, or with Bit 7 of the last character set. 
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If an error occurs on a system call, the C bit of Register CC is 
set, and Register B contains the error code. If no error occurs, 
the C bit is clear, and Register B contains a value of zero. 


User Mode System Calls Quick Reference 


Following is a summary of the User Mode System Calls refer- 
enced in this chapter: 


FSAIIBit 
F$Chain 
F$CmpNam 
F$CpyMem 
F$CRC 
F$DelBit 
FSExit 
F$Fork 
F$GBIkMp 
F$GModDr 
F$GPrDsc 
F$Icpt 
F$ID 
F$Link 
F$Load 
FSMem 
FSNMLink 


FSNMLoad 


F$Perr 
F$PrsNam 
F$SchBit 


Sets bits in an allocation bit map 
Chains a process to a new module 
Compares two names 

Copies external memory 

Generates a cyclic redundancy check 
Deallocates bits in an allocation bit map 
Terminates a process 

Starts a new process 

Gets a copy of a system block map 
Gets a copy of a module directory 
Gets a copy of a process descriptor 
Sets a signal intercept trap 

Returns a process ID 

Links to a memory module 

Loads a module from mass storage 
Changes a process’s data area size 


Links to a module; does not map the mod- 
ule into the user’s address space 


Loads a module but does not map it into the 
user’s address space 


Prints an error message 
Parses a pathlist name 


Searches a bit map 
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F$Send 
F$Sleep 
F$SPrior 
F$SSWI 
F$STime 
F$SUser 
F$Time 
F$UnLink 
F$UnLoad 
F$Wait 
I$Attach 
I$Chgdir 
I$Close 
I$Create 
I$Delete 
I$DeletX 
I$Detach 
I$Dup 
I$GetStt 
I$MakDir 
I$Open 
I$Read 
I$ReadLn 
I$Seek 
I$SetStt 
I$Write 
I$WritLn 
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Sends a signal to a process 
Suspends a process 

Sets a process’s priority 

Sets a software interrupt vector 
Sets the system time 

Sets the user ID number 
Returns the current time 
Unlinks a module 

Unlinks a module by name 
Waits for a signal 

Attaches an I/O device 

Changes a working directory 
Closes a path 

Creates a new file 

Deletes a file 

Deletes a file from the execution directory 
Detaches an I/O device 
Duplicates a path 

Gets a device’s status 

Creates a directory file 

Opens a path to an existing file 
Reads data from a device 

Reads a line of data from a device 
Positions a file pointer 

Sets a device’s status 

Writes data to a device 


Writes a data line to a device 
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System Mode Calls Quick Reference 


Following is a summary of the System Mode Calls referenced in 


this chapter: 
F$Alarm 
FSAI164 


FSANHRAM 


F$AllImg 
FS$AIIPre 
FSAILRAM 
FSAITsk 
F$AProc 
FS$Boot 
F$BtMem 
F$ClrBlk 
FS$DATLog 


F$Dellmg 
F$DelPre 
F$DelRAM 
F$DelTsk 
F$ELink 


FSF Modul 
F$Find64 
F$FreeHB 
F$FreeLB 
F$GCMDir 
F$GProcP 


Sets up an alarm 

Allocates a 64-byte memory block 
Allocates high RAM 

Allocates image RAM blocks 
Allocates a process descriptor 
Allocates RAM blocks 

Allocates a process task number 
Enters active process queue 
Performs a system bootstrap 
Performs a memory request bootstrap 
Clears the specified block of memory 


Converts a DAT block offset to a logical 
address 


Deallocates image RAM blocks 
Deallocates a process descriptor 
Deallocates RAM blocks 
Deallocates a process task number 


Links modules using a module directory 
entry 


Finds a module directory entry 
Finds a 64-byte memory block 
Gets a free high block 

Gets a free low block 

Compacts module directory entries 


Gets a process’s pointer 


8-5 


OS-9 Technical Reference 


F$IODel 
FSIOQu 
FSIRQ 
FSLDABX 
FSLDAXY 
FSLDDDXY 
F$MapBlk 
F$Move 
F$NProc 
FS$RelTsk 
F$ResTsk 
F$Ret64 
F$SetImg 
F$SetTsk 
F$SLink 
F$SRqMem 
FSSRtMem 
F$SSvec 
FSSTABX 
FSVIRQ 


F$V Modul 
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Deletes an I/O module 

Puts an entry into an I/O queue 
Makes an entry into IRQ polling table 
Loads Register A from 0,X in Task B 
Loads A[X,[Y]] 

Loads D[D + X,[Y]] 

Maps the specified block 

Moves data to a different address space 
Starts the next process 

Releases a task number 

Reserves a task number 

Returns a 64-byte memory block 

Sets a process DAT image 

Sets a process’s task DAT registers 
Performs a system link 

Performs a system memory request 
Performs a system memory return 
Installs a function request 

Stores Register A at 0,x in Task B 


Makes an entry in a virtual IRQ polling 
table 


Validates a module 
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Allocate Bits Sets bits in an 
OS9 F$AIIBit 103F 13 allocation bit map 


Entry Conditions: 


D =numeber of the first bit to set 
X = starting address of the allocation bit map 
Y = number of bits to set 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ Bit numbers range from 0 to n-1, where n is the number of 
bits in the allocation bit map. 


@ Warning: Do not issue the Allocate Bits call with Register 
Y set to 0 (a bit count of 0). 
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Chain Loads and executes a 
OS9 F$Chain 103F 05 new primary module 


without creating a new 
process 


Entry Conditions: 


A 


B 
X 
Y 
U 


= language/type code 

= size of the data area (in pages); must be at least one 
page 

= address of the module name or filename 

= parameter area size (in bytes); defaults to zero if not 
specified 

= starting address of the parameter area 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 
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Chain loads and executes a new primary module, but does 
not create a new process. A Chain system call is similar to 
a Fork followed by an Exit, but it has less processing over- 
head. Chain resets the calling process program and data 
memory areas and begins executing a new primary module. 
It does not affect open paths. This is a user mode system 
call. 


Warning: Make sure that the hardware stack pointer (Reg- 
ister SP) is located in the direct page before Chain exe- 
cutes. Otherwise the system might crash or return a 
suicide attempt error. This precaution also prevents a sui- 
cide in the event that the new module requires a smaller 
data area than that in use. Allow approximately 200 bytes 
of stack space for execution of the Chain system call. 


Chain performs the following steps: 


1. It causes OS-9 to unlink the process’s old primary 
module. 
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OS-9 parses the name string of the new process’s pri- 
mary module (the program that is to be executed first). 
Then, it causes OS-9 to search the system module 
directory to see if a module with the same name, type, 
and language is already in memory. 


If the module is in memory, it links to it. If the module 
is not in memory, it uses the name string as the path- 
list of a file to load into memory. Then, it links to the 
first module in this file. (Several modules can be loaded 
from a single file.) 


It reconfigures the data memory area to the size speci- 
fied in the new primary module’s header. 


It intercepts and erases any pending signals. 


The following diagram shows how Chain sets up the 
data memory area and registers for the new module. 


<+ Y (highest address) 


Parameter Area 
+ X,SP 


Data Area 


Direct Page 


+ U,DP (lowest address) 


= parameter area size 


module entry point absolute address 
F=0, I=0; others are undefined 


Registers Y and U (the top-of-memory and bottom-of-memory 
pointers, respectively) always have values at page boundaries. If 
the parent process does not specify a size for the parameter area, 
the size (Register D) defaults to zero. The data area must be at 
least one page long. 


(For more information, see the Fork system call.) 
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Compare Names Compares two strings 
OS9 F$CmpNam 103F 11 =F 2 Match 


Entry Conditions: 
B- = length of string1 
X = address of string! 
Y = address of string2 
Exit Conditions: 


CC =carry clear if the strings match 


Additional Information: 


@ The Compare Names call compares two strings and indi- 
cates whether they match. Use this call with the Parse 
Name system call. The second string must have the most 
significant bit (Bit 7) of the last character set. 
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Copy External Reads external memory 


; into the user’s buffer 
Memory for inspection 
OS9 F$CpyMem 
103F 1B 


Entry Conditions: 


= DAT image pointer 

= offset in block to begin copy 
byte count 

= caller’s destination buffer 


qk Ko 
] 


Error Output: 


CC =C bit set on error 
B = appropriate error code 


Additional Information: 


@ You can view any system memory through the use of the 
Copy External Memory call. The call assumes X is the 
address of the 64K space described by the DAT image 
given. 


@ If you pass the entire DAT image of a process, place a value 
in the X Register that equals the address in the process 
space. If you pass a partial DAT image (the upper half), 
then place a value in Register X that equals the offset from 
the beginning of the DAT image ($8000). 


@ The support module for this call is OS9p2. 
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CRC Calculates the CRC of 
OS9 F$CRC 103F 17 a module 


Entry Conditions: 


X = starting byte address 
Y  =numeber of bytes 
U = address of the 3-byte CRC accumulator 


Exit Conditions: 
Updates the CRC accumulator. 


Additional Information: 


@ The CRC call calculates the CRC (cyclic redundancy count) 
for use by compilers, assemblers, or other module 
generators. 


@ The calculation begins at the starting byte address and con- 
tinues over the specified number of bytes. 


@ You need not cover an entire module in one call, since the 
CRC can be accumulated over several calls. The CRC accu- 
mulator can be any 3-byte memory area. You must initial- 
ize it to $FFFFFF before the first CRC call. 


@ When checking an existing module CRC, the calculation 
should be performed on the entire module (including the 
module CRC). The CRC accumulator will contain the CRC 
constant bytes if the module CRC is correct. 


e If the CRC of a new module is to be generated, the CRC is 
accumulated over the module (excluding CRC). The accu- 
mulated CRC is complemented then stored in the correct 
position in the module. 


@ Be sure to initialize the CRC accumulator only once for 
each module checked by CRC. 
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Deallocate Bits Clears allocation map 
OS9 F$DelBit 103F 14 pits 


Entry Conditions: 


D =number of the first bit to set 
X = starting address of the allocation bit map 
Y = number of bits to set 


Exit Conditions: None 


Additional Information: 


@ The Deallocate Bits call clears bits in the allocation bit 
map pointed to by Register X. Bit numbers are in the 
range 0 to n-1, where n is the number of bits in the alloca- 
tion bit map. 


@ Warning: Do not call Deallocate Bits with Register Y set 
to 0 (a bit count of 0). 
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Exit Terminates the calling 
OS9 F$SExit 103F 06 process 


Entry Conditions: 


B 


= status code to return to the parent 


Exit Conditions: 


The process is terminated. 


Additional Information: 
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The Exit system call is the only way a process can termi- 
nate itself. Exit deallocates the process’s data memory 
area, and unlinks the process’s primary module. It also 
closes all open paths automatically. 


The Wait system call always returns to the parent the sta- 
tus code passed by the child in its Exit call. Therefore, if 
the parent executes a Wait and receives the status code, it 
knows the child has died. This is a user mode system call. 


Exit unlinks only the primary module. Unlink any module 
that is loaded or linked to by the process before calling 
Exit. 
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Fork Creates a child process 
OS9 F$Fork 103F 03 


Entry Conditions: 


A = language/type code 

B = size of the optional data area (in pages) 

X = address of the module name or filename (See the follow- 
ing example.) 

Y = size of the parameter area (in pages); defaults to zero if 
not specified 

U = starting address of the parameter area; must be at 
least one page 


Exit Conditions: 


X  =address of the last byte of the name + 1 (See the fol- 
lowing example.) 
A = new process IO number 


Error Output: 
B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ Fork creates a new process, a child of the calling process. 
Fork also sets up the child process’s memory and 6809 reg- 
isters and standard I/O paths. 


@ Before the Fork call: 


TLE} S| T| sop 


4 
Xx 
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e After the Fork call: 
4 


xX 
@ This is the sequence of Fork’s operations: 


1. OS-9 parses the name string of the new process’s pri- 
mary module (the program that OS-9 executes first). 
Then, it searches the system module directory to see if 
the program already is in memory. 


2a. The next step depends on whether or not the program is 
already in memory. If the program is in memory, OS-9 
links the module to the process and executes it. 


b. If the program is not in memory, OS-9 uses the name 
as the pathlist of the file that is to be loaded into mem- 
ory. Then, the first module in this file is linked to and 
executed. (Several modules can be loaded from one file.) 


3. OS-9 uses the primary module’s header to determine 
the initial size of the process’s data area. It then tries 
to allocate a contiguous RAM area of that size. (This 
area includes the parameter passing area, which is cop- 
ied from the parent process’s data area.) 


4. The new process’s data memory area and registers are 
set up as shown in the following diagram. OS-9 uses 
the execution offset given in the module header to set 
the program counter to the module’s entry point. 


Parameter Area 


+ Y 
«+ X,SP (highest address) 


Data Area 


Direct Page 


U,DP (lowest address) 
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D- = size of the parameter area 
PC = module entry point absolute address 
CC = F=0, I=0, other condition code flags are undefined 


Registers Y and U (the top-of-memory pointer and bottom- 
of-memory pointer, respectively) always have values at page 
boundaries. 


As stated earlier, if the parent does not specify the size of 
the parameter area, the size defaults to zero. The minimum 
overall data area size is one page. 


When the shell processes a command line, it passes a 
string in the parameter area. This string is a copy of the 
parameter part of the command line. To simplify string- 
oriented processing, the shell also inserts an end-of-line 
character at the end of the parameter string. 


Register X points to the start byte of the parameter string. 
If the command line includes the optional memory size 
specification (#n or #nK), the shell passes that size as the 
requested memory size when executing the Fork. 


If any of the preceding operations is unsuccessful, the Fork 
is terminated and OS-9 returns an error to the caller. 


The child and parent processes execute at the same time 
unless the parent executes a Wait system call immediately 
after the Fork. In this case, the parent waits until the child 
dies before it resumes execution. | 


Be careful when recursively calling a program that uses 
the Fork system call. Another child can be created with 
each new execution. This continues until the process table 
becomes full. 


Do not fork a process with a memory size of 0. 
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Get System Gets a copy of the 
Blo ek Map system block map 
OS9 F$GBIkMp 103F 19 ~ 


Entry Conditions: 
X = pointer to the 1024-byte buffer 


Exit Conditions: 


D =number of bytes per block ($2000) (MMU block size 
dependent) 
Y = system memory block map size 


Error Output: 


CC =carry set on error 
B = error code (if any) 
Additional Information: VY 


@ The Get System Block Map call copies the system’s memory 
block map into the user’s buffer for inspection. The OS-9 
MFREE command uses this call to find out how much free 
memory exists. 


@ The support module for this call is OS9p2. 
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Get Module Gets a copy of the 
Director system module 
y directory 


F$GModDr 103F 1A 


Entry Conditions: 

X = pointer to the 2048-byte buffer 

Y = end of copied module directory 

U = start address of system module directory 
Error Output: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


@ The Get Module Directory call copies the system’s module 
directory into the user’s buffer for inspection. The OS-9 
MDIR command uses this call to read the module 
directory. 


@ The support module for this call is OS9p2. 
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Get Process Gets a copy of the 
Descr1 tor process’s process 
P descriptor 


F$GPrDsc 103F 18 


Entry Conditions: 

A = requested process ID 

xX = pointer to a 512-byte buffer 
Error Output: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


@ The Get Process Descriptor call copies a process descriptor 
into the calling process’s buffer for inspection. The data in 
the process descriptor cannot be changed. The OS-9 PROCS 
command uses this call to get information about each exist- 
ing process. 


e@ The support module for this call is OS9pz2. 
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Intercept Sets a signal intercept 
OS9 F$Icpt 103F 09 ep 


Entry Conditions: 
X = address of the intercept routine 
U = starting address of the routine’s memory area 
Exit Conditions: 
Signals sent to the process cause the intercept routine to be 
called instead of the process being killed. 
Additional Information: 


@ Intercept tells OS-9 to set a signal intercept trap. Then, 
whenever the process receives a signal, OS-9 executes the 
process’s intercept routine. 


@ Store the address of the signal handler routine in Register 
X and the base address of the routine’s storage area in 
Register U. 


@ Once the signal trap is set, OS-9 can execute the intercept 
routine at any time because a signal can occur at any 
time. 


e@ Terminate the intercept routine with an RTI instruction. 


e Ifa process has not used the Intercept system call to set a 
signal trap, the process terminates if it receives a signal. 


@ This is the order in which F$lIcpt operates: 


1. When the process receives a signal, OS-9 sets Registers 
U and B as follows: 


U_ = starting address of the intercept routine’s 
memory area 
B- = signal code (process’s termination status) 


Note: The value of Register DP cannot be the 
same as it was when the Intercept call was 
made. 


2. After setting the registers, OS-9 transfers execution to 
the intercept routine. 
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Get ID Return’s a caller’s 
OS9 FSID 103F 0C process ID and user ID 


Entry Conditions: 


None 


Exit Conditions: 


A = process ID 
bf = user ID 


Additional Information: 


@ The process ID is a byte value in the range 1 to 255. OS-9 
assigns each process a unique process ID. 


@ The user ID is an integer from 0 to 65535. It is defined in 
the system password file, and is used by the file security 
system and a few other functions. Several processes can 
have the same user ID. 


@ On a single user system (such as the Color Computer 3), 
the user ID is inherited from CC3go, which forks the initial 
shell. 
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Link Links to a memory 
module that has the 

OS9 F$Link 103F 00 specified name, 

language, and type 


Entry Conditions: 


A = type/language byte 
X =address of the module name (See the following 
example.) 


Exit Conditions: 


A = type/language code 

B= attributes / revision level (if no error) 

X = address of the last byte of the module name + 1 (See 
the following example.) 

Y = module entry point absolute address 

U = module header absolute address 


Error Output: 


CC =C bit set if error encountered 


Additional Information: 


@ The module’s link count increases by one whenever Link 
references its name. Incrementing in this manner keeps 
track of how many processes are using the module. 


e If the module requested is not shareable (not re-entrant), 
only one process can link to it at a time. 


@ Before the Link call: 


N 
Xx 


@ After the Link call: 


4 
Xx 
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@ This is the order in which the Link call operates: 


1. OS-9 searches the module directory for a module that 
has the specified name, language, and type. 


2. If OS-9 finds the module, the address of the module’s 
header is returned in Register U, and the absolute 
address of the module’s execution entry point is 
returned in Register Y. (This, and other information is 
contained in the module header.) 


e If OS-9 doesn’t find the module—or if the type/language 
codes in the entry and exit conditions don’t match—OS-9 
returns one of the following errors: 


¢ Module not found 
¢ Module busy (not shareable and in use) 
¢ Incorrect or defective module header 
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Load Loads a module or 
OS9 F$Load 103F 01 modules from a file 


Entry Conditions: 


A = language/type code; 0 = any language/type 
X  =address of the pathlist (filename) (See the following 
example.) 


Exit Conditions: 


A = language/type code 

B = attributes / revision level (if no error) 

X = address of the last byte of the pathlist (filename) + 1 
(See the following example.) 

Y = primary module entry point address 

U = address of the module header 


Error Output: 


CC =carry set if error encountered 


Additional Information: 


@ The Load call loads one or more modules from the file spec- 
ified by a complete pathlist or from the working execution 
directory (if an incomplete pathlist is given). 


@ The file must have the execute access mode bit set. It also 
must contain one or more with proper module headers. 


@ OS-9 adds all modules loaded to the system module direc- 
tory. It links the first module read. The exit conditions 
apply only to the first module loaded. 


® Before the Load call: 
|‘ [p]o]/jalcic[r[s[R] cv sop] 
4 


Xx 
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After the Load call: 


(i {[plol/falc|ce|t|s{R|c} Vv sop | 
N 


WO 
X 
@ Possible errors: 
¢ Module directory full 
¢ Memory full 
¢ Errors that occur on the Open, Read, Close, and Link 
system calls 
UW 
Ww 
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Memory Changes process’s data 
OS9 F$Mem area size 
103F 07 


Entry Conditions: 
D = size of the new memory area (in bytes); 
0 = return current size and upper bound 
Exit Conditions: 
Y = address of the new memory area upper bound 
D = actual size of the new memory (in bytes) 
Error Output: 


CC 
B 


carry set on error 
error code (if any) 


Additional Information: 


@ The memory call expands or contracts the process’s data 
memory area to the specified size. Or, if you specify zero as 
the new size, the call returns the current size and upper 
boundaries of data memory. 


@ OS-9 rounds off the size to the next page boundary. In allo- 
cating additional memory, OS-9 continues upward from the 
previous highest address. In deallocating unneeded mem- 
ory, it continues downward from that address. 
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Link to a module Links to a module; 


OS9 F$NMLink does not map the 
103F 21 module into the user’s 


address space 


Entry Conditions: 


A = type/language byte 
X = address of the module name 


Exit Conditions: 


A = type/language code 

B = module revision 

X  =address of the last byte of the module name+1; any 
trailing blanks are skipped 

Y = storage requirement for the module 


Error Output: 


CC  =carry set on error 
B = error code if any 


Additional Information: 


e Although this call is similar to F$Link, it does not map 
the specified module into the user’s address space but does 
return the memory requirement for the module. A calling 
process can use this memory requirement information to 
fork a program with a maximum amount of space. 
F$NMLink can therefore fork larger programs than can be 
forked by F$Link. 
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Load a module Loads one or more 

OS9 F$SNMLoad modules from a file but 
: does not map the 

103F 22 : ; 

module into the user’s 

address space 


Entry Conditions: 


A = type/language byte 
X = address of the pathlist 


Exit Conditions: 


A = type/language code 

B = module revision 

X = address of the last byte of the pathlist+1 
Y = storage requirement for the module 


Error Output: 


CC =carry set on error 
B = error code if any 


Additional Information: 


@ If you do not provide a full pathlist for this call, it attempts 
to load from a file in the current execution directory. 


e Although this call is similar to F$Load, it does not map 
the specified module into the user’s address space but does 
return the memory requirement for the module. A calling 
process can use this memory requirement information to 
fork a program with a maximum amount of space. 
F$NMLoad can therefore fork larger programs than can be 
forked by F$Load. 
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Print Error Writes an error 
OS9 F$Perr 103F OF message to a specified 
path 


Entry Conditions: 


B = error code 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


e Print Error writes an error message to the standard error 
path for the specified process. By default, OS-9 shows: 


ERROR #decimal number 


@ The error reporting routine is vectored. Using the Set SVC 
system call, you can replace it with a more elaborate 
reporting module. 
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Parse Name Scans an input string 
OS9 F$PrsNam 103F 10 for a valid OS-9 name 


Entry Conditions: 
X = address of the pathlist (See the following example.) 


Exit Conditions: 
X = address of the optional slash + 1 


Y = address of the last character of the name +1 
A = trailing byte (delimiter character) 
B- = length of the name 


Error Output: 
CC =carry set 


B = error code 
Y  =address of the first non-delimiter character in the 
string 


Additional Information: 


e Parses, or scans, the input text string for a legal OS-9 
name. It terminates the name with any character that is 
not a legal name character. 


@ Parse Name is useful for processing pathlist arguments 
passed to new processes. 


® Because Parse Name processes only one name, you might 
need several calls to process a pathlist that has more than 
one name. As you can see from the following example, 
Parse Name finishes with Register Y in position for the 
next parse. 


e If Register Y was at the end of a pathlist, Parse Name 
returns a bad name error. It then moves the pointer in Reg- 
ister Y past any space characters so that it can parse the 
next pathlist in a command line. 
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@ Before the Parse Name call: 


/{Dlo}/ | PlAlY [R{OjL/ Lb |» |b | 
4 
X 


After the Parse Name call: 
/{D]o|/|PJAlY |RJO/LILI| 4] be | 
4 4 BS 2 


X x 
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Search Bits Searches a specified 


memory allocation bit 
OS9 F$SchBit 103F 12 map for a free memory 
block of a specified 


size 


Entry Conditions: 


D- = starting bit number 

X = starting address of the map 
Y = bit count (free bit block size) 
U = ending address of the map 


Error Output: 
CC =C bit set 


Exit Conditions: 


D  =starting bit number 
Y = bit count 


Additional Information: 


@ The Search Bit call searches the specified allocation bit 
map for a free block (cleared bits) of the required length. 
The search starts at the starting bit number. If no block of 
the specified size exists, the call returns with the carry set, 
starting bit number, and size of the largest block. 
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Send Sends a signal to a 
OS9 F$Send 103F 08 specified process 


Entry Conditions: 


A 
B 


= destination’s process ID 
= signal code 


Error Output: 


CC 


B 


carry set on error 
error code (if any) 


Additional Information: 
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The signal code is a single byte value in the range 0 
through 255. 


If the destination process is sleeping or waiting, OS-9 acti- 
vates the process so that the process can process the signal. 


If a signal trap is set up, F$Send executes the signal pro- 
cessing routine (Intercept). If none was set up, the signal 
terminates the destination process, and the signal code 
becomes the exit status. (See the Wait system call.) An 
exception is the wakeup signal; that signal does not cause 
the signal intercept routine to be executed. 


Signal codes are defined as follows: 


0 = System terminate 
(cannot be intercepted) 
1 = Wake up the process 
2 = Keyboard terminate 
3 = Keyboard interrupt 
128-255 = User defined 


If you try to send a signal to a process that has a signal 
pending, OS-9 cancels the current Send call, and returns 
an error. Issue a Sleep call for a few ticks; then, try again. 


The Sleep call saves CPU time. See the Intercept, Wait, 
and Sleep system calls for more information. 


( \ 


User System Calls / 8 


Sleep Temporarily turns off 


OS9 F$Sleep 103F 0A 


the calling process 


Entry Conditions: 


xX 


= One of the following: 
sleep time (in ticks) 
0 (sleep indefinitely) 
1 (sleep for the remainder of 
the current time slice) 


Exit Conditions: 


xX 


= sleep time minus the number of ticks that the process 
was asleep 


Error Output: 


CC 


B 


carry set on error 
error code (if any) 


Additional Information: 


If Register X contains 0, OS-9 turns the process off until it 
receives a signal. Putting a process to sleep is a good way 
to wait for a signal or interrupt without wasting CPU time. 


If Register X contains 1, OS-9 turns the process off for the 
remainder of the process’s current time slice. It inserts the 
process into the active process queue immediately. The pro- 
cess resumes execution when it reaches the front of the 
queue. 


If Register X contains an integer in the range 2-255, OS-9 
turns off the process for the specified number of ticks, n. It 
inserts the process into the active process queue after n-1 
ticks. The process resumes execution when it reaches the 
front of the queue. If the process receives a signal, it awak- 
ens before the time has elapsed. 


When you select processes among multiple windows, you 
might need to set sleep for two ticks. 
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Set Priority 


OS9 F$SPrior 103F 0D 


Entry Conditions: 
A = process ID 


B = priority 
0 = lowest 
255 = highest 
Error Output: 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


Changes the priority 
of a process 


@ Set Priority changes the process’s priority to the priority 
specified. A process can change another process’s priority 


only if it has the same user ID. 
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Set SWI Sets the SWI2 and 


OS9 F$SSWI 103F 0E SWIS8 vectors 


Entry Conditions: 

A = SWI type code 

X = address of the user software interrupt routine 
Exit Conditions: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


® Sets the interrupt vectors for SWI, SWI2 and SWI3 
instructions. 


@ Each process has its own local vectors. Each Set SWI call 
sets one type of vector according to the code number passed 
in Register A: 


1 = SWI 
2 = SWI2 
3 = SWI3 


@ When OS-9 creates a process, it initializes all three vectors 
with the address of the OS-9 service call processor. 


@ Warning: Microware-supplied software uses SWI2 to call 
OS-9. If you reset this vector, these programs cannot work. 
If you change all three vectors, you cannot call OS-9 at all. 
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Set Time Sets the system time 
OS9 F$STime 103F 16 ne Date 
Entry Conditions: 

X = relative address of the time packet 


Error Output: 


CC. = C bit set 
B = error code 


Additional Information: 


e Set Time sets the current system date and time and starts 
the system real-time clock. The date and time are passed 
in a time packet as follows. 


Relative 
Address Value 
0 year 
1 month 
z day 
3 hours 
4 minutes 
5 seconds 


Then, the call makes a link system call to find the clock. If 
the link is successful, OS-9 calls the clock initialization. 
The clock initialization: 


1. Sets up hardware dependent functions 


2. Sets up the F$Time system call via F$SSvec 
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Set User ID Changes the current 
user ID without 

Number checking for errors or 

F$SUser 103F 1C checking the ID 


number of the caller 


Entry Conditions: 


Y = desired user ID number 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e@ The support module for this call is OS9p1. 
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Time Gets the system date 
OS9 F$Time 103F 15 and time 


Entry Conditions: 
X = address of the area in which to store the date and time 
packet 
Exit Conditions: 
X = date and time 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ The Time call returns the current system date and time in 
the form of a 6-byte packet (in binary). OS-9 copies the 
packet to the address passed in Register X. 


@ The packet looks like this: 


Relative 
Address Value 
0 year 
z month 
2 day 
3 hours 
4 minutes 
5 seconds 


@ Time is a part of the clock module and it does not exist if 
no previous call to F$Time has been made. 
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Unlink Unlinks (removes 
p from memory) a 
OS9 F$UnLink 103F 02 wodule thatisnc 
in use and that has 
a link count of 0 


Entry Conditions: 
U = address of the module header 


Error Output: 


CC = carry set on error 
B = error code (if any) 


Additional Information: 


@ Unlink unlinks a module from the current process’s 
address space, decreases its link count by one and, if the 
link count becomes zero, returns the memory where the 
module was located to the system for use by other 
processes. 


@ You cannot unlink system modules or device drivers that 
are in use. 


@ Unlink operates in the following order: 


1. Unlink tells OS-9 that the calling process no longer 
needs the module. 


2. OS-9 decreases the module’s link count by one. 


When the resulting link count is zero, OS-9 destroys 
the module. 


If any other process is using the module, the module’s 
link count cannot fall to zero. Therefore, OS-9 does not 
destroy the module. 


@ If you pass a bad address, Unlink cannot find a module in 
the module directory and does not return an error. 
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Unlink Decrements a specified 
module’s link count, 

A Module and removes the 

By Name module from memory if 
the resulting link count 


F$UnLoad 103F 1D ; 
is zero 
Entry Conditions: 


A 
Xx 


module type 
pointer to module name 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


e This system call differs from Unlink in that it uses a 
pointer to the module name, instead of the address of the 
module header. 


@ The support module for this call is OS9pz2. 
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Wait Temporarily turns off a 
OS9 F$Wait 103F 04 calling process 


Entry Conditions: None 


Exit Conditions: 


A 
B 


= deceased child process’s ID 
= deceased child process’s exit status code (if no error) 


Error Output: 


CC =carry set on error 


B 


= error code if any 


Additional Information: 


The Wait call turns off the calling process until a child pro- 
cess dies, either by executing an Exit system call, or by 
receiving a signal. The Wait call helps you save system 
time. 


OS-9 returns the child’s process’s ID and exit status to the 
parent. If the child died because of a signal, the exit status 
byte (Register B) contains the signal code. 


If the caller has several children, OS-9 activates the caller 
when the first one dies. Therefore, you need to use one Wait 
system call to detect the termination of each child. 


OS-9 immediately reactivates the caller if a child dies 
before the Wait call. If the caller has no children, Wait 
returns an error. (See the Exit system call for more 
information. ) 


If the Wait call returns with the carry bit set, the Wait 
function was not successful. If the carry bit is cleared, Wait 
functioned normally and any error that occurred in the 
child process is returned in Register B. 
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I/O User System Calls 


Attach Attaches a device to 


the system or verifies 
OS9 I$Attach 103F 80 device attachment 


Entry Conditions: 


A = access mode 
X = address of the device name string 


Exit Conditions: 


X = updated past device name 
U —_ = address of the device table entry 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


e Attach does not reserve the device. It only prepares the 
device for later use by any process. 


@ OS-9 installs most devices automatically on startup. There- 
fore, you need to use Attach only when installing a device 
dynamically or when verifying the existence of a device. You 
need not use the Attach system call to perform routine I/O. 


e@ The access mode parameter specifies the read and/or write 
operations to be allowed. These are: 


Use any special device capabilities 
Read only 

Write only 

Update (read and write) 


0 
1 
2 
3 
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@ Attach operates in this sequence: 


1; 


2a. 


OS-9 searches the system module to see if memory con- 
tains a device descriptor that has the same name as the 
device. 


OS-9’s next operation depends on whether or not the 
device is already attached. If OS-9 finds the descriptor 
and if the device is not already attached, OS-9 links the 
device’s file manager and device driver. It then places 
the address of the manager and the driver in a new 
device table entry. OS-9 then allocates any memory 
needed by the device driver, and calls the driver’s ini- 
tialization routine which initializes the hardware. 


. If OS-9 finds the descriptor, and if the device is already 


attached, OS-9 verifies the attachment. 
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Change Directory Changes the working 
, directory of a process 
OS? I9Chgair Ish 20 to a directory specified 
by a pathlist 

Entry Conditions: 

A = access mode 

X = address of the pathlist 
Exit Conditions: 

X = updated past pathlist 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e If the access mode is read, write, or update, OS-9 changes 
the current data directory. If the access mode is execute, 
OS-9 changes the current execution directory. 


e@ The calling process must have read access to the directory 
specified (public read if the directory is not owned by the 
calling process). 


@ The access modes are: 


Read 

Write 

Update (read and write) 
Execute 


1 
2 
3 
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Close Path Terminates an I/O path 
OS9 I$Close 103F 8F 


Entry Conditions: 


A 


= path number 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 


Close Path terminates the I/O path to the file or device 
specified by path number. Until you use another Open, 
Dup, or Create system call for that path, you can no longer 
perform I/O to the file or device. 


If you close a path to a single-user device, the device 
becomes available to other requesting processes. OS-9 de- 
allocates internally managed buffers and descriptors. 


The Exit system call automatically closes all open paths. 
Therefore, you might not need to use the Close Path system 
call to close some paths. 


Do not close a standard I/O path unless you want to change 
the file or device to which it corresponds. 


Close Path performs an implied I$Detach call. If it causes 
the device link count to become 0, the device termination 
routine is executed. See I$Detach for additional 
information. 
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Create File Creates and opens a 
OS9 I$Create 103F 83 disk file 
Entry Conditions: 

A = access mode (write or update) 


B = file attributes 
X = address of the pathlist; (See the following example.) 


Exit Conditions: 


A = path number 
X  =address of the last byte of the pathlist + 1; skips any 
trailing blanks (See the following example.) 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ OS-9 parses the pathlist and enters the new filename in the 
specified directory. If you do not specify a directory, OS-9 
enters the new filename in the the working directory. 


@ OS-9 gives the file the attributes passed in Register B, 
which has bits defined as follows: 


Bit Definition 


Read 

Write 

Execute 
Public read 
Public write 
Public execute 
Shareable file 


@ The access mode parameter passed in Register A must have 
the write bit set if any data is to be written. These access 
codes are defined as follows: 2 = write; 3 = update. The 
mode affects the file only until the file is closed. 


OOP WNEF © 
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You can reopen the file in any access mode allowed by the 
file attributes. (See the Open system call.) 


Files opened for write can allow faster data transfer than 
those opened for update because update sometimes needs to 
pre-read sectors. 


If the execute bit (Bit 2) is set, the file is created in the 
working execution directory instead of the working data 
directory. 


Create File causes an implicit I$Attach call. If the device 
has not previously been attached, the device’s initialization 
routine is called. 


Later I/O calls use the path number to identify the file, 
until the file is closed. 


OS-9 does not allocate data storage for a file at creation. 
Instead, it allocates the storage either automatically when 
you first issue a write or explicitly by the Setstat 
subroutine. 


If the filename already exists in the directory, an error 
occurs. If the call specifies a non-multiple file device (such 
as a printer or terminal), Create behaves the same as 
Open. 


You cannot use Create to make directories. (See the Make 
Directory system call for instructions on how to do make 
directories. ) 


Before the Create File call: 


|/ | Dd] o}/|wlo/R|K| sop | 


4 
X 


After the Create File call: 
/|pjo}/{|wlo] RK | sop | 


N 
X 
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Delete File Deletes a specified disk 
OS9 I$Delete 103F 87 file 


Entry Conditions: 
X = address of the pathlist (See the following example.) 


Exit Conditions: 


X  =address of the last byte of the pathlist + 1; any trail- 
ing blanks are skipped (See the following example.) 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ The Delete File call deletes the disk file specified by the 
pathlist. The file must have write permission attributes | 
(public write, if the calling process is not the owner). An ~ 
attempt to delete a device results in an error. The caller 
must have non-shareable write access to the file or an error 
results. 


Example: 
Before the Delete File call: 
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Delete A File Deletes a file from the 


OS9 I$DeletX 103F 90 current data or current 
execution directory 


Entry Conditions: 
A = access mode 
X = address of the pathlist 
Exit Conditions: 
X = address of the last byte of the pathlist+1; any trailing 
blanks are skipped 
Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ The Delete A File call removes the disk file specified by the 
selected pathlist. This function is similar to I$Delete except 
that it accepts an access mode byte. If the access mode is 
execute, the call selects the current execution directory. 
Otherwise, it selects the current data directory. 


@ If a complete pathlist is provided (the pathlist begins with 
a slash (/), the access mode the call ignores the access 
mode. 


@ Only use this call to delete a file. If you attempt to use 
I$DeletX to delete a device, the system returns an error. 
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Detach Device Removes a device 


from the system 
OS9 I$Detach 103F 81 device table 


Entry Conditions: 
U = address of the device table entry 


Exit Conditions: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


® The Detach Device call removes a device from both the sys- 
tem and the system device table, assuming the device is not 
being used by another process. You must use this call to 
detach devices attached using the Attach system call. 
Attach and Detach are both used mainly by the IO man- 
ager. SCF also uses Attach and Detach to set up its second 
device (echo device). 


@ This is the sequence of the operation of Detach Device: 


1. Detach Device calls the device driver’s termination rou- 
tine. Then, OS-9 deallocates any memory assigned to 
the driver. 


2. QOS-9 unlinks the associated device driver and file man- 
ager modules. 


3. OS-9 then removes the driver, as long as no other mod- 
ule is using that driver. 
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D uplic ate Path Returns a synonymous 
OS9 I$Dup 103F 82 path number 


Entry Conditions: 
A = old path number (number of path to duplicate) 


Exit Conditions: 


A = new path number (if no error) 


Error Output: 


B = error code (if error encountered) 
CC =carry set on error 


Additional Information: 


@ The Duplicate Path returns another, synonymous path 
number for the file or device specified by the old path 
number. 


@ The shell uses the Duplicate Path call when it redirects 
L/O. 


@ System calls can use either path number (old or new) to 
operate on the same file or device. 


@ Make sure that no more than one process is performing I/O 
on any one path at the same time. Concurrent I/O on the 
same path can cause unpredictable results with RBF files. 


@ The I$Dup call always uses the lowest available path num- 
ber. This lets you manipulate standard I/O paths to contain 
any desired paths. 
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Get Status Returns the status of a 
OS9 I$GetStt 103F 8D file or device 


Entry Conditions: 

A = path number 

B = function code 
Error Output: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


@® The Status is a wildcard call. Use it to handle device 
parameters that: 


¢ Are not the same for all devices 
« Are highly hardware-dependent 
¢ Must be user-changeable 


@® The exact operation of the Get Status system call depends 
on the device driver and file manager associated with the 
path. A typical use is to determine a terminal’s parameters 
for such functions as backspace character and echo on/off. 
The Get Status call is commonly used with the Set Status 
call. 


@ The Get Status function codes that are currently defined 
are listed in the “Get Status System Calls” section. 
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Make Directory Creates and initializes 
OS9 I$MakDir 103F 85 a directory 


Entry Conditions: 
B = directory attributes 
X = address of the pathlist 
Exit Conditions: 
X = address of the last byte of the pathlist +1; Make Direc- 
tory skips trailing blanks. 
Error Output: 
B = error code (if any) 
CC =carry set on error 
Additional Information: 


@ The Make Directory call creates and initializes a directory 
as specified by the pathlist. The directory contains only two 
entries, one for itself (.) and one for its parent directory (..) 


@ OS-9 makes the calling process the owner of the directory. 


@ Because the Make Directory call does not open the direc- 
tory, it does not return a path number. 


@ The new directory automatically has its directory bit set in 
the access permission attributes. The remaining attributes 
are specified by the byte passed in Register B. The bits are 
defined as follows: 


ee 
et 


Definition 
Read 

Write 
Execute 
Public read 
Public write 
Public execute 
Single-user 
Don’t care 


IH OP CONF © 
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@ Before the Make Directory call: 


(7 [pjto[/ [ne [wp] 1[R| sop_ 


4 
X 


After the Make Directory call: 
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Open Path Opens a path to an 

existing file or device 
OS9 1$Open 103F 84 as specified by the 
pathlist 


Entry Conditions: 


A  =access mode (D S PE PW PRE W R) 
X = address of the pathlist (See the following example.) 


Exit Conditions: 


A = path number 
X = address of the last byte of the pathlist + 1 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 
@ OS-9 searches for the file in one of the following: 


¢ The directory specified by the pathlist if the pathlist 
begins with a slash. 


¢ The working data directory, if the pathlist does not 
begin with a slash. 


¢ The working execution directory, if the pathlist does not 
begin with a slash and if the execution bit is set in the 
access mode. 


@ OS-9 returns a path number for later system calls to use to 
identify the file. 


@ The access mode parameter lets you specify which read 
and/or write operations are to be permitted. When set, each 
access mode bit enables one of the following: Write, Read, 
Read and Write, Update, Directory I/O. 


@ The access mode must conform to the access permission 
attributes associated with the file or device. (See the Cre- 
ate system call.) Only the owner can access a file unless 
the appropriate public permission bits are set. 
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@ The update mode might be slightly slower than the others 
because it might require pre-reading of sectors for random 
access of bytes within sectors. 


@ Several processes (users) can open files at the same time. 
Each device has an attribute that specifies whether or not 
it is shareable. 


@ Before the Open Path call: 
/|Diol/jale|{c|r{s|P/a]¥| sop 
4 


X 
After the Open Path call: 


/{pio|/{alce|c|t{s|Plaly] sop 
N 


X 


e@ If the single-user bit is set, the file is opened for single-user 
access regardless of the settings of the file’s permission 


bits. WwW 
@ You must open directory files for read or write if the direc- 
tory bit (Bit 7) is set in the access mode. 


@ Open Path always uses the lowest path number available 
for the process. 
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Read Reads n bytes from a 
OS9 I$Read 103F 89 specified path 


Entry Conditions: 


A 
bs 
X 


= path number 
= number of bytes to read 
= address in which to store the data 


Exit Conditions: 


ba 


= number of bytes read 


Error Output: 


B 


= error code (if any) 


CC =carry set on error 


Additional Information: 


The Read call reads the specified number of bytes from the 
specified path. It returns the data exactly as read from the 
file/device, without additional processing or editing. The 
path must be opened in the read or update mode. 


If there is not enough data in the specified file to satisfy 
the read request, the call reads fewer bytes than requested 
but an end-of-file error is not returned. After all data in a 
file is read, the next I$Read call returns an end-of-file 
error. 


If the specified file is open for update, the record read is 
locked out on RBF-type devices. 


The keyboard terminate, keyboard interrupt, and end-of-file 
characters are filtered out of the Entry Conditions data on 
SCF-type devices unless the corresponding entries in the 
path descriptor have been set to zero. You might want to 
modify the device descriptor so that these values are ini- 
tialized to zero when the path is opened. 
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@ The call reads the number of bytes requested unless Read 
encounters any of the following: 


¢ An end-of-file character 
¢ An end-of-record character (SCF only) 


e An error 
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Read Line With Reads a text line with 
Editing editing 


OS9 I$ReadLn 103F 8B 


Entry Conditions: 


A = path number 
X = address at which to store data 
Y = maximum number of bytes to read 


Exit Conditions: 


Y  =number of bytes read 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ Read Line is similar to Read. The difference is that Read 
Line reads the input file or device until it encounters a car- 
riage return character or until it reaches the maximum 
byte count specified, whichever comes first. The Read Line 
also automatically activates line editing on character ori- 
ented devices, such as terminals and printers. The line 
editing refers to auto line feed, null padding at the end of 
the line, backspacing, line deleting, and so on. 


@ SCF requires that the last byte entered be an end-of-record 
character (usually a carriage return). If more data is 
entered than the maximum specified, Read Line does not 
accept it and a PD.OVF character (usually a bell) is 
echoed. 


@ After one Read Line call reads all data in a file, the next 
Read Line call generates an end-of-file error. 


@ (For more information about line editing, see “SCF Line 
Editing Functions” in Chapter 6.) 
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Seek Repositions a file 
OS9 I$Seek 103F 88 pointer 


Entry Conditions: 


A 
Xx 
U 


= path number 
= MS 16 bits of the desired file position 
= LS 16 bits of the desired file position 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 
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The Seek Call repositions the path’s logical file pointer, the 
32-bit address of the next byte in the file to be read from or 
written to. 


You can perform a seek to any value, regardless of the file’s 
size. Later writes automatically expand the file to the 
required size (if possible). Later reads, however, return an 
end-of-file condition. Note that a seek to Address 0 is the 
same as a rewind operation. 


OS-9 usually ignores seeks to non-random access devices, 
and returns without error. 


On RBF devices, seeking to a new disk sector causes the 
internal disk buffer to be rewritten to disk if it has been 
modified. Seek does not change the state of record locking. 
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Set Status Sets the status of a file 
OS9 I$SetStt 103F 8E or device 


Entry Conditions: 


A = path number 

B = function code 

Other registers depend on the function code. 
Error Output: 


B = error code (if any) 

CC =carry set on error 

Other registers depend on the function code. 
Additional Information: 


@ Set Status is a wildcard call. Use it to handle device 
parameters that: 


¢ Are not the same for all devices 
¢ Are highly hardware-dependent 
¢ Must be user-changeable 


@ The exact operation of the Set Status system call depends 
on the device driver and file manager associated with the 
path. A typical use is to set a terminal’s parameters for 
such functions as backspace character and echo on/off. The 
Set Status call is commonly used with the Get Status call. 


@ The Set Status function codes that are currently defined 
are listed in the “Set Status System Calls” section. 
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Write Writes to a file or 
OS9 I$Write 103F 8A device 


Entry Conditions: 


A = path number 
X = starting address of data to write 
Y = number of bytes to write 


Exit Conditions: 


Y = number of bytes written 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ The Write system call writes to the file or device associated 
with the path number specified. 


® Before using Write, be sure the path is opened or created 
in the Write or Update access mode. OS-9 writes data to 
the file or device without processing or editing the data. 
OS-9 automatically expands the file if you write data past 
the present end-of-file. 
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Write Line Writes to a file or 
‘ device until it 
OS9 I$WritLn 103F 8C encounters a carriage 
return 


Entry Conditions: 


A = path number 
X = address of the data to write 
Y = maximum number of bytes to write 


Exit Conditions: 


Y = number of bytes written 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ Writes to the file or device that is associated with the path 
number specified. 


@ Write Line is similar to Write. The difference is that Write 
Line writes data until it encounters a carriage return char- 
acter. It also activates line editing for character-oriented 
devices, such as terminals and printers. The line editing 
refers to auto line feed, null padding at the end of the line, 
backspacing, line deleting, and so on. 


@ Before using Write Line, be sure the path is opened or cre- 
ated in the write or update access mode. 


@ (For more information about line editing, see “SCF Line 
Editing Functions” in Chapter 6.) 
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Privileged System Mode Calls 


Set an alarm Sets an alarm to ring 
OS9 F$Alarm 103F 1E wih ada eine 
ime 
Entry Conditions: 
X = relative address of time packet 


Error Output: 

CC =carry set on error 

B = appropriate error code 
Additional Information: 


@ When the system reaches the specified alarm time, it rings 
the bell for 15 seconds. 


e The time packet is identical to the packet used in the 
F$STime call. See F$STime for additional information on 
the format of the packet. 


e All alarms begin at the start of a minute and any seconds 
in the packet are ignored. 


@ The system is limited to one alarm at a time. 


8-66 


Privileged System Mode Calls / 8 


Allocate 64 Dynamically allocates 


OS9 F$All64 103F 30 64-byte blocks of 
memory 


Entry Conditions: 


X = base address of the page table; 0 = the page table has 
not been allocated 


Exit Conditions: 


A = block number 
X = base address of the page table 
Y  =address of the block 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ The Allocate 64 system call allocates the 64-byte blocks of 
memory by splitting pages (256-byte sections) into four 
sections. 


@ OS-9 uses the first 64 bytes of the base page as a page 
table. This table contains the page number (most signifi- 
cant byte of the address) of all pages in the memory struc- 
ture. If Register X passes a value of zero, the call allocates 
a new base page and the first 64-byte memory block. 


@ Whenever a new page is needed, a Request System Memory 
system call (F$SRqMem) executes automatically. 


@ The first byte of each block contains the block number. 
Routines that use the Allocate 64 call should not alter this 
byte. 
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@ The following diagram shows how seven blocks might be 


allocated: 


Base Page > 


Page Table 


(64 bytes) 


xX 
Block 1 
(64 bytes) 


».4 
Block 2 
(64 bytes) 


xX 
Block 3 
(64 bytes) 
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Any Memory Page 


4 
Block 4 
(64 bytes) 


X 


Block 5 
(64 bytes) 


xX 
Block 6 
(64 bytes) 


XxX 
Block 7 
(64 bytes) 
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Allocate High Allocate system 
RAM memory from high 


physical memory 
OS9 F$AlIHRam_ = 103F 53 


Entry Conditions: 
B = number of blocks 


Error Output: 

CC =carry set on error 

B = appropriate error code 
Additional Information: 


@ This call searches for the desired number of contiguous free 
RAM blocks, starting its search at the top of memory. 
F$AllHRam is similar to F$AlLRAM except F$AlIITRAM 
begins its search at the bottom of memory. 


@ Screen allocation routines use this call to provide a better 
chance of finding the necessary memory for a screen. 
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Allocate Image Allocates RAM 


blocks for process 
OS9 F$AllImg 103F 3A DAT image 


Entry Conditions: 


A = starting block number 
B = number of blocks 
X = process descriptor pointer 


Exit Conditions: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ Use the Allocate Image system call to allocate a data area 
for a process. The blocks that Allocate Image defines might 
not be contiguous. 


e The support module for this system call is OS9p1. 
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Allocate Process Aliocates and 

initializes a 512-byte 
Descriptor process descriptor 
OS9 F$AllPre 103F 4B 


Entry Conditions: None 


Exit Conditions: 


U = process descriptor pointer 


Error Output: 


CC =C bit set on error 
B = appropriate error code 


Additional Information: 


@ The process descriptor table houses the address of the 
descriptor. Initialization of the process descriptor consists 
of clearing the first 256 bytes of the descriptor, setting up 
the state as a system state, and marking as unallocated as 
much of the DAT image as the system allows—typically, 
60-64 kilobytes. 


@ The support module for this system call is OS9p2. The call 
also branches to the F$SRqMem call. 
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Allocate RAM Searches the 
memory block map 

OS9 FSAIIRAM 103F 39 fe the desired 
number of 
contiguous free 
RAM blocks 


Entry Conditions: 
B = number of blocks 


Exit Conditions: 

CC =C bit set on error 

B = appropriate error code 
Additional Information: 


e The support module for this system call is OS9p1. 


Privileged System Mode Calls / 8 


Allocate Pp rOCe@SS Determines whether 


, OS-9 has assigned a 
Task Number task number to the 
OS9 F$AITsk 103F 3F specified process 


Entry Conditions: 


X = process descriptor pointer 


Error Output: 

CC =C bit set 

B = = appropriate error code 
Additional Information: 


@ If the process does not have a task number, OS-9 allocates 
a task number and copies the DAT image into the DAT 
hardware. 


@ The support module for this call is OS9p1. Allocate Process 
Task number also branches to F$ResTsk and F$SetT'sk. 
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Insert Process Inserts a process into 
OS9 F$AProc 103F 2C the queue for execution 


Entry Conditions: 
X = address of the process descriptor 


Error Output: 


CC 
B 


carry set on error 
error code (if any) 


Additional Information: 


@ The Insert Process system call inserts a process into the 
active process queue so that OS-9 can schedule the process 
for execution. 


e OS-9 sorts all processes in the queue by process age (the 
count of how many process switches have occurred since the 
process’s last time slice). When a process is moved to the 
active process queue, OS-9 sets its age according to its 
priority—the higher the priority, the higher the age. 


An exception is a newly active process that was deactivated 
while in the system state. OS-9 gives such a process higher 
priority because the process usually is executing critical 
routines that affect shared system resources. 
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Bootstrap System Links either the 
OS9 F$Boot 103F 35 module named Boot 
| or the module 
specified in the INIT 
module 


Entry Conditions: None 


Error Output: 

CC =C bit set on error 

B = appropriate error code 
Additional Information: 


@ When it calls the linked module, Boot expects to receive a 
pointer giving it the location and size of an area in which 
to search for the new module. 


@ The support module for this call is OS9p1. Bootstrap Sys- 
tem also branches to the F$Link and F$VModul system 
calls. 
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Bootstrap Allocates the 
requested memory 
Memory Request (a icd to the 
OS9 F$BtMem 103F 36 nearest block) as 
contiguous memory 
in the system’s 
address space 
Entry Conditions: 


D = byte count requested 


Exit Conditions: 
D- = byte count granted 
U = pointer to memory allocated 
Error Output: 
CC =C bit set on error 
B = _ = appropriate error code 
Additional Information: 
@ This call is identical to F$SRqMem. 
@ The Bootstrap Memory Request support module is OS9pl1. 
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Clear Specified Marks blocks in the 
Block process DAT image as 


unallocated 
OS9 F$ClrBlk 103F 50 


Entry Conditions: 

B = number of blocks 

U = address of first block 
Exit Conditions: None 


Additional Information: 


e@ After Clear Specified Block deallocates blocks, the blocks 
are free for the process to use for other data or program 
areas. If the block address passed to Clear Specified Block 
is invalid or if the call attempts to clear the stack area, it 
returns E$IBA. 


@ The support module for the call is OS9p2. 
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DAT to Logical Converts a DAT image 


clock number and 
Address block offset to its 
OS9 F$DATLog 103F 44 equivalent logical 
address 


Entry Conditions: 


B = DAT image offset 
X = = block offset 


Exit Conditions: 
X = logical address 


Error Output: 


CC =C bit set on error 
B = appropriate error code 


Additional Information: 


@ Following is a sample conversion: 


2000 - 2FFF 
1000 - 1FFF 
0 - FFF 


@ The support module for this call is OS9p1. 


Input: B = 2 
$0329 


Output: X = $2329 
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Deallocate Image Deallocates image 
R AM Blocks RAM blocks 


OS9 F$DelImg 103F 3B 


Entry Conditions: 


A = number of starting block 
B = block count 
X = process descriptor pointer 


Error Output: 
CC =C bit set on error 
B = appropriate error code 


Additional Information: 


@ This system call deallocates memory from a process’s 
address space. It frees the RAM for system use and frees 
the DAT image for the process. Its main use is to let the 
system clean up after a process death. 


@ The support module for this call is OS9p2. 
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Deallocate Returns a process 
Proce SS descriptor’s memory to 


‘ a free memory pool 
Descriptor 
OS9 F$DelPrc 103F 4C 


Entry Conditions: 


A = process ID 


Error Output: 

CC =C bit set on error 

B = appropriate error code 
Additional Information: 


@ Use this call to clear the system scratch memory and stack 
area associated with the process. 


e@ The support module for this call is OS9p2. 
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Deallocate RAM Clears a block’s RAM 
blocks In Use flag in the 


system memory block 
OS9 F$DelIRAM 103F 51 map 


Entry Conditions: 

B = number of blocks 

X = starting block number 
Exit Conditions: None 


Additional Information: 


@ The Deallocate RAM Blocks call assumes the blocks being 
deallocated are not associated with any DAT image. 


@ The support module for this call is OS9p2. 


8-81 


OS-9 Technical Reference 


Deallocate Task Releases the task 


Numb er number that the 

process specified by WwW 
OS9 F$DelTsk 103F 40 the passed descriptor 

pointer 


Entry Conditions: 


X = process descriptor pointer 


Error Output: 


CC =C bit set on error 
B = appropriate error code 


Additional Information: 


@ The support module for this call is OS9p1. 
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Link Using Performs a link using a 
Module Directory pointer to a module 


directory entry 
Entry 
OS9 F$ELink 103F 4D 


Entry Conditions: 

B = module type 

X = pointer to module directory entry 
Exit Conditions: 

U = module header address 

Y = module entry point 
Error Output: 

CC =C bit set on error 

B = appropriate error code 
Additional Information: 


@ This call differs from Link in that you supply a pointer to 
the module directory entry rather than a pointer to a mod- 
ule name. 


@ The support module for this call is OS9p1. 
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Find Module Returns a pointer to 
Directory Entry the module directory 
OS9 F$FModul 103F 4E 


entry 


Entry Conditions: 


A 
X 
x 


= module type 
= pointer to the name string 
= DAT image pointer (for name) 


Exit Conditions: 


A 
B 
X 


U 


= module type 

= module revision number 

= updated name string; (if Register A contains 0 on 
entry) 

= module directory entry pointer 


Error Output: 
CC =C bit set on error 


B 


= appropriate error code 


Additional Information: 


8-84 


The Find Module Directory Entry call returns a pointer to 
the module directory entry for the first module that has a 
name and type matching the specified name and type. If 
you pass a module type of zero, the system call finds any 
module. 


The support module for this call is OS9p1. 


Privileged System Mode Calls / 8 


Find 64 Returns the address 
OS9 F$Find64 103F 2F OL Ee CMOEY 
block 
Entry Conditions: 
A = block number 
X = address of the block 
Exit Conditions: 
Y = address of the block 
CC =carry set if block not allowed or not in use 


Additional Information: 


@ OS-9 uses Find 64 to find path descriptors when given 
their block number. The block number can be any positive 
integer. 
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Get Free High Searches the DAT 
image for the 

Block highest set of 

OS9 F$FreeHB 103F 3E contiguous free 


blocks of the 
specified size 
Entry Conditions: 
B = block count 
Y = DAT image pointer 
Exit Conditions: 


A =starting block number 


Error Output: 

CC =C bit set on error 

B = = appropriate error code 
Additional Information: 


® The Get Free High Block call returns the block number of 
the beginning memory address of the free blocks. 


@ The support module for this system call is OS9p1. 
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Get Free Low Searches the DAT 
image for the lowest set 

Block of contiguous free 

OS9 F$FreeLB 103F 3D blocks of the specified 
size 


Entry Conditions: 

B = block count 

Y = DAT image pointer 
Exit Conditions: 


A = starting block number 


Error Output: 

CC =C bit set on error 

B = appropriate error code 
Additional Information: 


@ The Get Free Low Block call returns the block number of 
the beginning memory address of the free blocks. 


@ The support module for this system call is OS9p1. 
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Compact Module Compacts the entries in 
Directory the module directory 
OS9 FSGCMDir 103F 52 


Entry Conditions: None 
Exit Conditions: None 


Additional Information: 


e@ This function is only for internal OS-9 system use. You 
should never call it from a program. 
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Get Process Gets a pointer to a 
Pointer prawns 
F$GProcP 103F 37 


Entry Conditions: 
A = process ID 


Exit Conditions: 


B = = pointer to process descriptor (if no error) 


Error Output: 

CC =carry set on error 

B = error code (If an error occurs (E$BPrcID)) 
Additional Information: 


@ The Get Process Pointer call translates a process ID num- 
ber to the address of its process descriptor in the system 
address space. Process descriptors exist only in the system 
task address space. Because of this, the address returned 
only refers to system address space. 


@ The support module for this call is OS9p2. 
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1/ O Delete Deletes an I/O module 
OS9 F$IODel 103F 33 that is not being used 


Entry Conditions: 
X = address of an I/O module 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ The I/O Delete deletes the specified I/O module from the 
system, if the module is not in use. This system call is 
used mainly by the I/O MANAGER, and can be of limited 
or no use for other applications. 


@ This is the order in which I/O Delete operates: 


1. Register X passes the address of a device descriptor 
module, device driver module, or file manager module. 


2. OS-9 searches the device table for the address. 


3. If OS-9 finds the address, it checks the module’s use 
count. If the count is zero, the module is not being 
used; OS-9 deletes it. If the count is not zero, the mod- 
ule is being used; OS-9 returns an error. 


e I/O Delete returns information to the Unlink system call 
after determining whether a device is busy. 
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LV/O Queue Inserts the calling 
process into another 

OS9 FSIOQu 103F 2B process’s I/O queue, 
and puts the calling 
process to sleep 


Entry Conditions: 


A = process number 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ The I/O Queue call links the calling process into the I/O 
queue of the specified process and performs an untimed 
sleep. The IO Manager and the file managers are primary 
and extensive users of I/O Queue. 


@ Routines associated with the specified process send a wake- 
up signal to the calling process. 


OS-9 Technical Reference 


Set IRQ Adds a device to or 


OS9 F$IRQ 103F 2A removes it from the 


polling table 


Entry Conditions: 


D 
X 


bs 
U 


= address of the device status register 
= 0 (to remove a device) or the address of a packet (to 
add a device) 
@ the address at X is the flip byte 
® the address at X+1 is the mask byte 
@ the address at X +2 is the priority byte 
= address of the device IRQ service routine 
= address of the service routine’s memory area 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 
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Set IRQ is used mainly by device driver routines. (See 
“Interrupt Processing” in Chapter 2 for a complete discus- 
sion of the interrupt polling system.) 


Packet Definitions: 


The Flip Byte. Determines whether the bits in the device 
status register indicate active when set or active when 
cleared. If a bit in the flip byte is set, it indicates that the 
task is active whenever the corresponding bit in the status 
register is clear (and vice versa). 


The Mask Byte. Selects one or more bits within the device 
status register that are interrupt request flag(s). One or 
more set bits identify which task or device is active. 


The Priority Byte. Contains the device priority number (0 
= lowest priority, 255 = highest priority). 


Privileged System Mode Calls / 8 


Load A F rom Loads A from 0,X in 


F$LDABX 103F 49 


Entry Conditions: 
B= task number 
X = pointer to data 
Exit Conditions: 
A = byte at 0,X in task address space 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e@ The value in Register X is an offset value from the begin- 
ning address of the Task module. The Load A From Task B 
call returns one byte from this logical address. Use this 
system call to get one byte from the current process’s mem- 
ory in a system state routine. 
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Get One Byte Loads A from [X, [YJ] 
F$LDAXY 103F 46 


Entry Conditions: 


X 
Y 


= block offset 
= DAT image pointer 


Exit Conditions: 


A 


= contents of byte at DAT image (Y) offset by X 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 
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The Get One Byte system call gets the contents of one byte 
in the specified memory block. The block is specified by the 
DAT image in (Y), offset by (X). The call assumes that the 
DAT image pointer is to the actual block desired, and that 
X is only an offset within the DAT block. The value in Reg- 
ister X must be less than the size of the DAT block. OS-9 
does not check to see if X is out of range. 


a 
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Get Two Bytes Loads D from 
F$LDDDXY 103F 48 [D+ X],[Y] 


Entry Conditions: 


D = Offset to the offset within the DAT image 
X = Offset within the DAT image 
Y = DAT image pointer 


Exit Conditions: 
D  ~=contents of two bytes at [D+ X,Y] 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ Get Two Bytes loads two bytes from the address space 
described by the DAT image pointer. If the DAT image 
pointer is to the entire DAT, then make D+ X equal to the 
process address for data. If the DAT image is not the entire 
image (64K), then you must adjust D+X relative to the 
beginning of the DAT image. Using D+ X lets you keep a 
local pointer within a block, and also lets you point to an 
offset within the DAT image that points to a specified block 
number. 
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Map Specific Maps the specified 

Block block(s) into 
unallocated blocks of 

F$MapBlk 103F 4F process space 


Entry Conditions: 
X = starting block number 
B = number of blocks 
Exit Conditions: 
U = address of first block 


Error Output: 
B = error code (if any) 
CC =carry set on error 
Additional Information: 


@ The system maps blocks from the top down. It maps new 
blocks into the highest available addresses in the address 
space. See Clear Specified Block for information on 
unmapping. 
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Move Data Moves data bytes from 
F$Move 103F 38 one address space to 
another 


Entry Conditions: 


= source task number 

= destination task number 
source pointer 

= byte count 

= destination pointer 


CK Kw SP 
| il 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ You can use the Move Data system call to move data bytes 
from one address space to another, usually from system to 
user, or vice versa. 


@ The support module for this call is OS9p1. 
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Next Process Executes the next 


OS9 F$NProc 103F 2D process in the active 
process queue 


Entry Conditions: None 


Exit Conditions: 


Control does not return to caller. 


Additional Information: 


@ The Next Process system call takes the next process out of 
the active process queue and initiates its execution. If the 
queue contains no process, OS-9 waits for an interrupt, and 
then checks the queue again. 


@ The process calling Next Process must already be in one of 
the three process queues. If it is not, it becomes unknown 
to the system even though the process descriptor still exists 
and can be displayed by a PROCS command. 
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Release A Task Releases a specified 
F$RelTsk 103F 43 DAT task number from 
use by a process, 
making the task’s DAT 
hardware available for 
use by another task 


Entry Conditions: 


B = task number 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ The support module for this call OS9p1. 
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Re serve Task Reserves a DAT task 
Number number 
F$ResTsk 103F 42 


Entry Conditions: none 


Exit Conditions: 


B = task number (if no error) 


Error Output: 

CC =carry set on error 

B = error code if an error occurs 
Additional Information: 


@ The Reserve Task Number call finds a free DAT task num- 
ber, reserves it, and returns the task number to the caller. 
The caller often then assigns the task number to a process. 


@ The support module for this call is OS9p1. 
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Return 64 Deallocates a 64-byte 
OS9 F$Ret64 103F 31 block of memory 


Entry Conditions: 

A = block number 

X = address of the base page 
Error Output: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


@ See the Allocate 64 system call for more information. 
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Set Process DAT Copies all or part of 

the DAT image into a 
Image process descriptor 
F$SetImg 103F 3C 


Entry Condition: 


= starting image block number 
= block count 

process descriptor pointer 

= new image pointer 


Cx WLS 
| 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ While copying part or all of the DAT image, this system 
call also sets an image change flag in the process descrip- 
tor. This flag guarantees that as a process returns from 
the system call. The call updates the hardware to match 
the new process DAT image. 


@ The support module for this call is OS9p1. 
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Set Process Task writes to the hardware 
DAT Registers DAT registers 


F$SetTsk 103F 41 


Entry Conditions: 


X = pointer to process descriptor 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ This system call sets the process task hardware DAT regis- 
ters, and clears the image change flag in the process 
descriptor. It also writes to DAT RAM the process’s seg- 
ment address information. 


@ The support module for this call is OS9p1. 
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System Link Adds a module from 
‘ outside the current 
F$SLink 103F 34 address space into the 
current address space 


Entry Conditions: 


A = module type 
X = module name string pointer 
Y  =name string DAT image pointer 


Exit Conditions: 


module type 

module revision (if no error) 
updated name string pointer 
module entry point 

module pointer 


CK Kw Pp 
lou ue ue ll 


Error Output: 
CC =carry set on error 
= error code (If an error occurs) 
Additional Information: 


@ The I/O System uses the System Link call to link into the 
current process’s address space those modules specified by a 
device name in a user call. User calls such as Create File 
and Open Path use this System Link. 


@ The support module for this call is OS9p1. 
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Request System Allocates a block of 
memory of the 

Memory specified size from the 

OS9 F$SRqMem 103F 28 top of available RAM 


Entry Conditions: 
D- = byte count 


Exit Conditions: 
U = starting address of the memory area 
D =new memory size 
Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ The Request System Memory call rounds the size request 
to the next page boundary. 


@ This call allocates memory only for system address space. 
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Return System Deallocates a block of 
Memory contiguous pages 
OS9 F$SRtMem 103F 29 


Entry Conditions: 


U = starting address of memory to return; must point to an 
even page boundary 
D =number of bytes to return 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 
@ Register U must point to an even page boundary. 


@ This call deallocates memory for system address space only. 
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Set SVC Adds or replaces a 


OS9 F$SSve 103F 32 system call 


Entry Conditions: 
Y = address of the system call 
initialization table 
Error Output: 
COC =. bit set 
B = error code 
Additional Information: 


@ Set SVC adds or replaces a system call, which you have 
written, to OS-9’s user and system mode system call tables. 


@ Register Y passes the address of a table, which contains the 
function codes and offsets, to the corresponding system call 
handler routines. This table has the following format: 


Relative Use 


Address 
$00 

Function Code + First entry 
$01 __ Offset From Byte 3 __ 
$02 To Function Handler 
$03 Function Code < Second entry 
$04 Offset From Byte 6 
$05 To Function Handler _ 

More Entries + More entries 

$80 + End-of-table mark 
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If the most significant bit of the function code is set, OS-9 
updates the system table. 


If the most significant bit of the function code is not set, 
OS-9 updates the system and user tables. 


The function request codes are in the range $29-$34. IO 
calls are in the range $80-$90 


To use a privileged system call, you must be executing a 
program that resides in the system map and that executes 
in the system state. 


The system call handler routine must process the system 
call and return from the subroutine with an RTS 
instruction. 


The handler routine might alter all CPU registers (except 
Register SP). 


Register U passes the address of the register stack to the 
system call handler as shown in the following diagram: 


Relative Name 
Address 

$00 | RSCC 
$01 R$D 
$01 RSA 
$02 R$B 
$03 RSDP 
$04 R$X 
$06 RSY 
$08 R$U 
$0A R$PC 


Codes $70-$7F are reserved for user definition. 
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Store A Byte Stores A at 0,X in 
In A Task | tase) 


FSSTABX 103F 4A 


Entry Conditions: 


A = byte to store 
B = destination task number 
X = logical destination address 


Error Output: 
CC = carry set on error 
B = error code (if any) 
Additional Information: 


@ This system call is similar to the assembly language 
instruction “STA 0,X”. The difference is that in the system 
call, X refers to an address in the given task’s address 
space, instead of the current address space. 


@ The support module for this system call is OS9p1. 
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Install virtual Installs a virtual 
interrupt interrupt handler 
p routine 


OS9 F$VIRQ 103F 27 


Entry Conditions: 


D- = initial count value 
X = 0 to delete entry 
1 to install entry 
Y = address of 5-byte packet 


Error Output: 


CC =carry set on error 
B = appropriate error code 


Additional Information: 


@ Install VIRQ for use with devices in the Multi-Pak Expan- 


sion Interface. This call is explained in detail in Chapter 2. 
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Validate Module Checks the module 


OS9 F$VModul 103F 2E header parity and CRC 
bytes of a module 


Entry Conditions: 

D- = = DAT image pointer 

X = new module block offset 
Exit Conditions: 


U = address of the module directory entry 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e If the values of the specified module are valid, OS-9 
searches the module directory for a module with the same 
name. If one exists, OS-9 keeps in memory the module that 
has the higher revision level. If both modules have the save 
revision level, OS-9 retains the module in memory. 
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Get Status System Calls 


You use the Get Status system calls with the RBF manager sub- 
routine GETSTA. The OS-9 Level Two system reserves function Wy 
Codes 7-127 for use by Microware. You can define Codes 128-255 

and their parameter-passing conventions for your own use. (See 

the sections on device drivers in Chapters 4, 5, and 6.) 


The Get Status routine passes the register stack and the speci- 
fied function code to the device driver. 


Following are the Get Status functions and their codes. 


SS.OPT 


(Function code $00). Reads the option section of the path 
descriptor, and copies it into the 32-byte area pointed to by Reg- 
ister X 


Entry Conditions: 


A = path number 
= WY 
X = address to receive status packet 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ Use SS.OPT to determine the current settings for editing 
functions, such as echo and auto line feed. 
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SS.RDY 


(Function code $01). Tests for data available on SCF-supported 
devices 


Entry Conditions: 


A = path number 
B = $01 


Exit Conditions: 


If the device is ready: 
CC =carry clear 
B = $00 


If the device is not ready: 
CC =carry set 
B = $F6 (ES$SRNDY) 


Error Output: 


CC =carry set 
B = error code 


SS.SIZ 


(Function code $02). Gets the current file size on a RBF-sup- 
ported devices only 


Entry Conditions: 


A = path number 
B = $02 
Exit Conditions: 
X = most significant 16 bits of the current file size 
U- = least significant 16 bits of the current file size 


Error Output: 


CC =carry set on error 
B- =error code (if any) 


8-113 


OS-9 Technical Reference 


SS.POS 


(Function code $05). Gets the current file position (RBF-sup- 
ported devices only) 


Entry Conditions: 


A = path number 
B = $05 
Exit Conditions: 
X = most significant 16 bits of the current file position 
U = least significant 16 bits of the current file position 


Error Output: 


CC =carry set on error 
B = error code (if any) 
SS.EOF 


(Function code $06). Tests for the end of the file (EOF) 
Entry Conditions: 


A = path number 
B = $06 


Exit Conditions: 
If there is no EOF: 


CC = earry clear 
B = $00 


If there is an EOF: 
CC =carry set 
B = $D3 (E$SEOF) 


Error Output: 


CC =carry set 
B = error code 
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SS.DevNm 
(Function Code $0E). Returns a device name 
Entry Conditions: 


A = path number 
B = $0E 
X = address of 32-byte buffer for name 


Exit Conditions: 
X = address of buffer, name moved to buffer 


SS.DSTAT 
(Function code $12). Returns the display status 
Entry Conditions: 


A = path number 
B = $12 


Exit Conditions: 


A =color code of the pixel at the cursor address 
X = address of the graphics display memory 
Y = graphics cursor address; X = MSB, Y = LSB 


Additional Information: 


@ This function is supported only with the VDGINT module 
and deals with VDG-compatible graphics screens. See 
SS.AAGBf for information regarding Level Two operation. 


8-115 


OS-9 Technical Reference 


SS.JOY 
(Function code $13). Returns the joystick values 


Entry Conditions: 


A = path number 
B =6$13 
X = joystick number 


0 = (right joystick) 
1 = (left joystick) 


Exit Conditions: 


A = fire button down 

0 = none 

1 = Button 1 

2 = Button 2 

3 = Button 1 and Button 2 
X = selected joystick x value (0-63) 
Y = selected joystick y value (0-63) 

Note: Under Level 1, the following values are returned by 
this call: 

A = fire button status 

$FF = fire button is on 

$00 = fire button is off 
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SS.AlfaS 


(Function code $1C). Returns VDG alpha screen memory 
information 


Entry Conditions: 


A = path number 
B =$1C 


Exit Conditions: 


A =caps lock status 

$00 = lower case 

SFF = upper case 
X = memory address of the buffer 
Y = = memory address of the cursor 


Additional Information: 


@ SS.AlfaS maps the screen into the user address space. The 
call requires a full block of memory for screen mapping. 
This call is only for use with VDG text screens handled by 
VDGINT. 


@ The support module for this call is VDGINT. 


@ Warning: Use extreme care when poking the screen, since 
other system variables reside in screen memory. Do not 
change any addresses outside of the screen. 
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SS.Cursr 


(Function code $25). Returns VDG alpha screen cursor 
information 


Entry Conditions: 


A = path number 
B =$25 
Exit Conditions: 
A =character code of the character at the current cursor 
address 
X  =cursor X position (column) 
Y  =cursor Y position (row) 


Additional Information: 


e SS.Cursr returns the character at the current cursor posi- 
tion. It also returns the X-Y address of the cursor relative 
to the current device’s window or screen. SS.Cursr works 
only with text screens. 


@ The support module for this call is VDGINT. 
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SS.ScSiz 
(Function code $26). Returns the window or screen size 
Entry Conditions: 


A = path number 
B = $26 


Exit Conditions: 


X = number of columns on screen/window 
Y = number of rows on screen/window 


Additional Information: 


@ Use this call to determine the size of an output screen. The 
values returned depend on the device in use: 


For non-CCIO devices, the call returns the values follow- 
ing the XON/XOFF bytes in the device descriptor. 


For CCIO devices, the call returns the size of the window 
or screen in use by the specified device. 


For window devices. the call returns the size of the cur- 
rent working area of the window. 


@ The support modules for this call are VDGINT, GrflInt, and 
WindInt. 
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SS.KySns 


(Function code $27). Returns key down status 


Entry Conditions: 


A 
B 


Exit 
A 


= path number 
= $27 


Conditions: 


= keyboard scan information 


Additional Information: 
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Accumulator A returns with a bit pattern representing 
eight keys. With each keyboard scan, OS9 updates this bit 
pattern. A set bit (1) indicates that a key was pressed since 
the last scan. A clear bit (0) indicates that a key was not 
pressed. Definitions for the bits are as follows: 


Bit Key 

0 

or 
or 

(up arrow) 
(down arrow) 
(left arrow) 
(right arrow) 
Space Bar 


“ID OP GDF 


The bits can be masked with the following equates: 


SHIFTBIT equ %00000001 
CNTRLBIT equ %00000010 
ALTERBIT equ %00000100 
UPBIT equ %00001000 
DOWNBIT equ %00010000 
LEFTBIT equ %00100000 
RIGHTBIT equ %01000000 
SPACEBIT equ %10000000 


The support module for this call is CC3IO. 
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SS.ComSt 


(Function code $28). Return serial port configuration 
information 


Entry Conditions: 


A = path number 
B = $28 
Exit Conditions: 
Y  =high byte: parity 


low byte: baud rate 
(See the Setstat call SS.ComSt for values) 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ The SCF manager uses this call when performing an 
SS.Opt Getstat on an SCF-type device. User calls to 
SS.ComSt do not update the path descriptor. Use the 
SS.OPT Getstat call for most applications, because it auto- 
matically updates the path descriptor. 
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SS.MnSel 


(Function code $87). Requests that the high-level menu handler 
take control of menu selection 


Entry Conditions: 


A = path number 
B = $87 
Exit Conditions: 
A = menu ID (if valid selection) 
O (if invalid selection) 
B = item number of menu (if valid selection) 


Error Output: 


CC =carry set on error 
B = error code (if invalid selection) 


Additional Information: 


e After detecting a valid mouse click (when the mouse is 
pointing to a control area on a window), a process needs to 
call SS.MnSel. This call tells the enhanced window inter- 
face to handle any menu selection being made. If accumula- 
tor A returns with 0, then no selection has been made. The 
calling process needs to test and handle other returned 
values. 


e A condition where Register A returns a valid menu ID 
number and Register B returns 0 signals the selection of a 
menu with no items. The application can now take over and 
do a special graphics pull down of its own. The menu title 
remains highlighted until the application calls the 
SS.UMBar SetStat to update the menu bar. 


e@ The support module for this call is WindInt. 
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SS.Mouse 
(Function code $89). Gets mouse status 
Entry Conditions: 


A = path number 
B = $89 
X = data storage area address 
Y = = mouse port select: 
0 = automatic selection 


1 = right side 
2 = left side 
Exit Conditions: 
X = data storage area address 
Error Output: 
CC =carry set on error 
B = error code (if any) 
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Additional Information: 


e SS.Mouse returns information on the current mouse and its 
fire button. The following list defines the 32-byte data 
packet that SS.Mouse creates: 
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Pt. Valid rmb 1 Is returned info valid? (O=no, 
1 = yes) 
Pt.Actv rmb 1 Active side (0 = off, 1 = right, 2 = 
left) 
Pt. ToTm rmb 1 Timeout initial value 
PeTris rmb 1 Time until timeout 
rmb 2 RESERVED 
Pt.TSSt rmb 2 Time since counter start 
Pt.CBSA rmb 1 Current button state (Button A) 
Pt.CBSB rmb 1 Current button state (Button B) 
Pt.CcCtA rmb 1 Click count (Button A) 
Pt.CCtB rmb 1 Click count (Button B) 
Pt.TTSA rmb 1 Time this state counter (Button A) 
Pt.TTSB rmb 1 Time this state counter (Button B) 
Pt.TLSA rmb 1 Time last state counter (Button A) 
Pt.TLSB rmb 1 Time last state counter (Button B) 
rmb 2 RESERVED 
Pt.BDX rmb 2 Button down frozen Actual X 
Pt. BDY rmb 2 Button down frozen Actual Y 
Pt.Stat rmb 1 Window pointer type location 
Pt.Res rmb 1 Resolution (0-640 by 0=10/1=1) 
Pt.AcX rmb 2 Actual X value 
Pt.AcY rmb 2 Actual Y value 
Pt.WRX rmb 2 Window relative X 
Pt. WRY rmb 2 Window relative Y 
Pt.Siz equ . Packet size 32 bytes 
SPt.SRX rmb 2 System use, screen relative X 
SPt.SRY rmb 2 System use, screen relative Y 
SPt.Siz equ . Size of packet for system use 


Button Information: 


Pt.Valid. The valid byte gives the caller an indication of 
whether the information contained in the returned packet 
is accurate. The information returned by this call is only 
valid if the process is running on the current interactive 
window. If the process is on a non-interactive window, the 
byte is zero and the process can ignore the information 
returned. | 
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Pt.Actv. This byte shows which port is selected for use by 
all mouse functions. The default value is Right (1). You can 
change this value with the SS.GIP Setstat call. 


Pt.ToTm. This is the initial value used by Pt.TTTo. 


Pt.TTTo. This is the count down value (as of the instant 
the Getstat call is made). This value starts at the value 
contained in the Pt.ToTm and counts down to zero at a rate 
of 60 counts per second. The system maintains all counters 
until this value reaches 0, at which point it sets all 
counters and states to 0. The mouse scan routine changes 
into a quiet mode which requires less overhead than when 
the mouse is active. The timeout begins when both buttons 
are in the up (open) state. The timer is reinitialized to the 
value in Pt.ToTm when either button goes down (closed). 


Pt.TSSt. This counter is constantly increasing, beginning 
when either button is pressed while the mouse is in the 
quiet state. All counts are a number of ticks (60 per sec- 
ond). The timer counts to $FFFF, then stays at that value 
if additional ticks occur. 


Pt.CBSA. These flag bytes indicate the state of the button 
Pt.CBSB. at the last system clock tick. A value of 0 indi- 
cates that the button is up (open).. A value other than zero 
indicates that the button is down (closed). Button A is 
available on all Tandy joysticks and mice. Button B is only 
available for products that have two buttons. 


The system scans the mouse buttons each time it scans the 
keyboard. 


Pt.CCtA. This is the number of clicks that have occurred 
Pt.CCtB. since the mouse went into an active state. A 
click is defined as pressing (closing) the button, then releas- 
ing (opening) the button. The system counts the clicks as 
the button is released. 


Pt.TTSA. This counter is the number of ticks that have 
Pt.TTSB. occurred during the current state, as defined by 
Pt.CBSx. This counter starts at one (counts the tick when 
the state changes) and increases by one for each tick that 
occurs while the button remains in the same state (open or 
closed). 
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Pt.TLSA. This counter is the number of ticks that have 
Pt.TLSB. occurred during the time that a button is in a 
state opposite of the current state. Using this count and 
the TTSA/TTSB count, you can determine how a button 
was in the previous state, even if the system returns the 
packet after the state has changed. Use these counters, 
along with the state and click count values, to define any 
type of click, drag, or hold convention you want. 


Reserved. Two packet bytes are reserved for future expan- 
sion of the returned data. 


Position Information: 


Pt.BDX. These values are copies of the Pt.AcX and Pt.AcY 
Pt.BDY. values when either of the buttons change from an 
open state to a closed state. 


Pt.Stat. This byte contains information about the area of 
the screen on which the mouse is positioned. Pt. Valid must 
be a value other than 0 for this information to be accurate. 
If Pt. Valid is 0, this value is also 0 and not accurate. Three 
types of areas are currently defined: 


0 = content region or current working area of the 
window 

1 = control region (for use by Multi- View) 

2 = off window, or on an area of the screen that is not 


part of the window 


Pt.Res. This value is the current resolution for the mouse. 
The mouse must always return coordinates in the range of 
0-639 for the X axis and 0-191 for the Y axis. If the system 
is so configured, you can use the high-resolution mouse 
adapter which provides a 1 to 1 ratio with these values plus 
1. If the adapter is not in use, the resolution is a ratio of 1 
to 10 on the X axis and 1 to 3 on the Y axis. The keyboard 
mouse provides a resolution of 1 to 1. The values in Pt.Res 
are: 

0 

1 


Pt.AcX. The values read from the mouse returned in the 
Pt.AcyY. resolution as described under Pt.Res. 


low res (x:10, y:3) 
high res (x,y:1) 
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Pt.WRX. The values read from the mouse minus the 
Pt.WRY. starting coordinates of the current window’s 

es working area. These values return the coordinates in num- 

| bers relative to the type of screen. For example, the X axis 
is in the range 0-639 for high-resolution screens and 0-319 
for low resolution screens. You can divide the window rela- 
tive values by 8 to obtain absolute character positions. 
These values are most helpful when working in non-scaled 
modes. 


@ The support modules for this call are CC3I0O, GrfInt, and 
WindInt. 


SS.Palet 
(Function code $91). Gets palette information 


Entry Conditions: 


A = path number 
B =6$91 
oo X = pointer to the 16-byte palette information buffer 


Exit Conditions: 


X = pointer to the 16-byte palette information buffer 
Additional Information: 


@ SS.Palet reads the contents of the 16 screen palette regis- 
ters, and stores them in a 16-byte buffer. When you make 
the call, be sure the X register points to the desired buffer 
location. The pointer is retained on exit. The palette values 
returned are specific to the screen on which the call is 
made. 


@ The support modules for this call are VDGINT, Grfint, and 
WindInt. 
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SS.ScTyp 


(Function code $93). Returns the type of a screen to a calling 
program. 


Entry Conditions: 


A = path 
B = $93 


Exit Conditions: 


A =screen type code 

oe = 40 x 24 text screen 
80 x 24 text screen 
not used 
not used 
640 x 192, 2-color graphics screen 
320 x 192, 4-color graphics screen 
640 x 192, 4-color graphics screen 
320 x 192, 16-color graphics screen 


COmNI OS) OP OC DO 
low ue i ul ell 


Additional Information: 


@ Support modules for this system call are GrfInt and 
WindInt. 
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SS.FBRgs 


(Function code $96). Returns the foreground, background and 
border palette registers for a window. 


Entry Conditions: 


A = path number 

B = $96 
Exit Conditions: 

A = foreground palette register number 

B= background palette register number (if carry clear) 

X = least significant byte of border palette register number 
Error Output: 

B = error code if any 

CC =carry set on error 


Additional Information: 
@ Support modules for SS.FBRgs are GrfInt and WindInt. 


SS.DFPal 


(Function code $97). Returns the default palette register 
settings. 


Entry Conditions: 


A = path number 
B = $97 
X = pointer to 16-byte data space 


Exit Conditions: 
X = default palette data moved to user space 
Error Output: 


B  =error code, if any 
CC =carry set on error 
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Additional Information: 


e You can use SS.DFPal to find the values of the default pal- 
ette registers that are used when a new screen is allocated 
by GrfInt or WindInt. The corresponding SetStat can alter 
the default registers. This GetStat/SetStat pair is for sys- 
tem configuration utilities and should not be used by gen- 
eral applications. 


Set Status System Calls 


Use the Set Status system calls with the RBF manager subrou- 
tine SETSTA. The OS-9 Level Two system reserves function 
Codes 7-127 for use by Microware. You can define Codes 200-255 
and their parameter-passing conventions for your own use. (See 
the sections on device drivers in Chapters 4, 5, and 6.) 


Following are the Set Status functions and their codes. 


SS.OPT 


(Function code $00). Writes the option section of the path 
descriptor 


Entry Conditions: 


A = path number 

B = 4600 

X = address of the status packet 
Error Output: 

CC =carry set on error 

B = error code (if any) 


Additional Information: 


@e SS.OPT writes the option section of the path descriptor 
from the 32-byte status packet pointed to by Register X. 
Use this system call to set the device operating parameters, 
such as echo and line feed. 
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SS.SIZ 


(Function code $02). Changes the size of a file for RBF-type 
devices 


Entry Conditions: 


A = path number 

B =$02 

X = most significant 16 bits of the desired file size 
U- = least significant 16 bits of the desired file size 


Error Output: 


CC =carry set on error 
B = error code (if any) 
SS.RESET 


(Function code $03). Restores the disk drive head to Track 0 in 
preparation for formatting and error recovery (use only with 
RBF-type devices) 


Entry Conditions: 


A = path number 
B = $03 
Error Output: 
CC =carry set on error 
B = error code (if any) 
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SS.WTRK 


(Function code $04). Formats (writes) a track on a disk (RBF- 
type devices only) 


Entry Conditions: 


A = path number 
B = $04 
U = track number (least significant 8 bits) 


X = address of the track buffer 
Y = = side/density 


Bit BO = side 
0 = Side 0 
1 = Side 1 
Bit Bl = density 
0 = single 
1 = double 
Error Output: 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ For hard disks or floppy disks that have a “format entire 
diskette command,” SS.WTRK formats the entire disk only 
when the track number is zero. 
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SS.SQD 


(Function code $0C). Starts the shutdown procedure for a hard 
disk that has sequence-down requirements prior to removal of 
power. (Use only with RBF-type devices.) 


Entry Conditions: 


A = path number 
B = $0C 


Exit Conditions: None 


SS.KySns 
(Function code $27). Turns the key sense function on and off 


Entry Conditions: 


A = path number 
B = $27 
X = key sense switch value 


normal key operation 


1 = key sense operation 
Error Output: 
CC =carry set on error 
B= error code (if any) 


Additional Information: 


@ When SS.KySns switches the keyboard to key sense mode, 
the CC3IO module suspends transmission of keyboard char- 
acters to the SCF manager and the user. While the com- 
puter is in key sense mode, the only way to detect key press 
is with SS.KySns. 


@ The support module for this call is CC3IO. 
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SS.ComSt 


(Function code $28). Used by the SCF manager to configure a 
serial port 


Entry Conditions: 


A = path number 
B = $28 
Y  =high byte: parity 


low byte: baud rate 
Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


Baud Configuration. The high order byte of Y determines the 
baud rate, the word length, and number of stop bits. The byte is 
configured as follows: 


poBpau |!7le6elsl4a4i3l2iilo! 


oom sual Baud rate 
Reserved 
Word length 


Stop bits 
Stop bits: 
Oo 1 
Ie 2 
Word length: 
00 = 8 bit 
O17 Dit 
Baud rate: 
0000 = 110 
0001 = 300 
0010 = 600 
UOLL = 1200 
0100 = 2400 
0101 = 4800 
0110 = 9600 
O111 — 19200 
1xxx = undefined 
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e Parity Configuration. The low order byte of Y determines 
parity. The byte is configured as follows: 


PD.BAU |71l6lsl4i3il2lilo| 


Special use 


Parity 
Parity: 
xx0 = none 
001 = odd (ACIAPAK and MODPAK only) 
011 = even (ACIAPAK and MODPAK only) 
101 = transmit: mark 
receive: ignore 
111 = transmit: space 


receive: ignore 


@ The SCF manager uses SS.ComSt to inform a driver that 
serial port configuration information has been changed in 
the path descriptor. After calling SS.ComSt, a user routine 
must call the SS.OPT SetStat to correctly update the path 
descriptor. 


e@ This call is for the use of the SCF manager. Use SS.OPT 
for changing baud, stop bit, and parity values. 


SS.Close 


(Function code $2A). Informs a device driver that a path is 
closed. 


Additional Information: 


This call is used internally by OS-9’s SCF file manager and is 
not available for user programs. It can be used only by device 
drivers and file managers. 
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SS.AAGBf 
(Function code $80). Reserves an additional graphics buffer 
Entry Conditions: 


A = path number 
B = $80 


Exit Conditions: 


X = buffer address 
Y = buffer number (1-2) 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e SS.AAGBf allocates an additional 8K graphics buffer. The 
first buffer (Buffer 0) must be allocated by using the DIS- 
PLAY GRAPHICS command. To use the DISPLAY GRAPH- 
ICS command, send control code $0F to the standard 
terminal driver. SS.AAGBf can allocate up to two addi- 
tional buffers (Buffers 1 and 2), one at a time. 


e After calling SS.AAGBf, Register X contains the address of 
the new buffer. Register Y contains the buffer number. 


@ To deallocate all graphics buffers, use the END GRAPHICS 
control code. 


@ When SS.AAGBf allocates a buffer, it also maps the buffer 
into the application’s address space. Each buffer uses 8K of 
the available memory in the application’s address space. 
Also, if SS.DStat is called, Buffer 0 is also mapped into the 
application’s address space. Allocation of all three buffers 
reduces the application’s free memory by 24K. 


@ The support module for this call is VDGINT. 
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SS.SLGBf 
(Function code $81). Selects a graphics buffer 


Entry Conditions: 


A 
B 
X 


xX 


= path number 
= $81 
= $00 select buffer for use 
$01-$FF select buffer for use and display 
= buffer number (0-2) 


Exit Conditions: 


X 
¥ 


unchanged from entry 
unchanged from entry 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 


Use DISPLAY GRAPHICS to allocate the first graphics 
buffer. Use SS.AAGBf to allocate the second and third 
graphics buffers. 


Save each return address when writing directly to a screen. 
It is not necessary to save return addresses when using 
operating system graphics commands. 


SS.SLGBf does not update hardware information until the 
next vertical retrace (60Hz rate). Programs that use 
SS.AAGBf to change current draw buffers need to wait long 
enough to ensure that OS-9 has moved the current buffer to 
the screen. 


The screen shows the buffer only if the buffer is selected as 
the interactive device. If the device does not possess the 
keyboard, OS-9 stores the information until the device is 
selected as the interactive device. When the device is 
selected as the interactive device, the display shows the 
selected device’s screen. 


The support module for this call is VDGINT. 
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SS.MpGPB 


(Function code $84). Maps the Get/Put buffer into a user 
address space 


Entry Conditions: 


A = path number 
B = $84 
X =high byte: buffer group number 
low byte: buffer number 
Y = action to take 
1 = map buffer 
0 = unmap buffer 


Exit Conditions: 


X = address of the mapped buffer 


Y = number of bytes in buffer 
Error Output: 

CC =carry set on error 

B = error code (if any) 


Additional Information: 
@ The support modules for this call are GrfInt and WindInt. 


@ SS.MpGPB maps a Get/Put buffer into the user address 
space. You can then save the buffer to disk or directly mod- 
ify the pixel data contained in the buffer. Use extreme care 
when modifying the buffer so that you do not write outside 
of the buffer data area. 
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SS.WnSet 
(Function code $86). Set up a high level window handler 
Entry Conditions: 


A = path number 
B = $86 
xX window data pointer (if Y= WT.FSWin or WT.Win) 


4 
Error Output: 


window type code 


CC =carry set on error 
B  =error code (if any) 


Additional Information: 


@ The C language data structures for windowing are defined 
in the wind.h file in the DEFS directory of the system disk. 


e@ The support module for this call is WindInt. 


SS.SBar 
(Function code $88). Puts a scroll block at a specified position 


Entry Conditions: 


A = path number 

B = $88 

X = horizontal position of scroll block 

Y = vertical position of scroll block 
Error Output: 

CC =carry set on error 

B = error code (if any) 


Additional Information: 


@ WT.FSWin-type windows have areas at the bottom and 
right sides to indicate their relative positions within a 
larger area. These areas are called scroll bars. SS.SBar 
gives an application the ability to maintain relative posi- 
tion markers within the scroll bars. The markers indicate 
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the location of the current screen within a larger screen. 
Calling SS.SBar, updates both scroll markers. 


@ The support module for this call is WindInt. 


SS.Mouse 


(Function code $89). Sets the sample rate and button timeout 
for a mouse 


Entry Conditions: 


A = path number 
B = $89 
X = mouse sample rate and timeout 


most significant byte = mouse sample rate 
least significant byte = mouse timeout 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ SS. Mouse allows the application to define the mouse 
parameters. The sample rate is the number of clock ticks 
between the actual readings of the mouse status. 


@ The support module for the call is CC3I0O. 
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SS.MsSig 


(Function code $8A). Sends a signal to a process when the 
mouse button is pressed 


Entry Conditions: 
A = path number 


B = $8A 

X = user defined signal code (low byte only) 
Error Output: 

CC =carry set on error 

B = error code (if any) 


Additional Information: 


® SS.MsSig sends the process a signal the next time a mouse 
button changes state (from open to closed). Once SS.MsSig 
sends the signal, the process must repeat the Setstat each 
time that it needs to set up the signal. 


@ Processes using SS.MsSig should have an intercept routine 
to trap the signal. By intercepting the signal, other pro- 
cesses can be notified when the change occurs. Therefore, 
the other processes do not need to continually poll the 
mouse. 


e The SS.Relea Setstat clears the pending signal request, if 
desired. It also clears any pending signal from SS.SSig. 
Because of this, if you want to clear only one signal, you 
must reset the other signal after calling SS.MsSig. 


@ The support module for this call is CC3I0. 
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SS.AScrn 


(Function code $8B). Allocates and maps a high-resolution 
screen into an application address space 


Entry Conditions: 


A = path number 
B = $8B 
X = screen type 
= 640 x 192 x 2 colors (16K) 
1 = 320 x 192 x 4 colors (16K) 
2 = 160 x 192 x 16 colors (16K) 
3 = 640 x 192 x 4 colors (32K) 
4 = 320 x 192 x 16 colors (32K) 
Exit Conditions: 
X = application address space of screen 
Y = screen number (1-3) 
Error Output: 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


SS.AScrn is particularly useful in systems with minimal 
memory when you want to allocate a high resolution graph- 
ics screen with all screen updating handled by a process. 


This call uses VDGInt (GRFINT is not required). 


All screens are allocated in multiples of 8K blocks. You can 
allocate a maximum of three buffers at one time. To select 
between buffers, use the SS.DScrn Setstat call. 


Screen memory is allocated but not cleared. The application 
using the screen must do this. 


Screens must be allocated from a VDG-type device—a 
standard 32-column text screen must be available for the 
device. 


The support module for this call is VDGINT. 
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SS.DScrn 


(Function code $8C). Causes VDGINT to display a screen that 
was allocated by SS.AScrn 


Entry Conditions: 


A = path number 
B = $8C 
x = screen number (1-3) 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ SS.DScrn shows the requested screen if the requested 
screen is the current interactive device. 


@ The support module for this call is VDGINT. 
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SS.FScrn 


(Function code $8D). Frees the memory of a screen allocated 
by SS.AScrn 


Entry Conditions: 


A = path number 
B = $8D 
¥ = screen number (1-3) 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ Do not attempt to free a screen that is currently on the 
display. 


e SS.FScrn returns the screen memory to the system and 
removes it from an application’s address space. 


@ The support module for this call is VDGINT. 
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SS.PScrn 
(Function code $8E). Converts a screen to a different type 


Entry Conditions: 


A = path number 

B = $8E 

X = new screen type 
0 = 640 x 192 x 2 colors (16K) 
1 = 820 x 192 x 4 colors (16K) 
2 = 160 x 192 x 16 colors (16K) 
3 = 640 x 192 x 4 colors (32K) 
4 = 320 x 192 x 16 colors (32K) 

Es = screen number 


Error Output: 


CC = carry set on error 
B = error code (if any) 


Additional Information: 


@ SS.PScrn changes a screen allocated by SS.AScrn to a new 
screen type. You can change a 32K screen to either a 32K 
screen, or a 16K screen. You can change a 16K screen only 
to another 16K screen type. SS.PScrn updates the current 
display screen at the next clock interrupt. 


@ However, if you change a 32K screen to a 16K screen, OS-9 
does not reclaim the extra 16K of memory. This means 
that you can later change the 16K screen back to a 32K 
screen. 


@ The support module for this call is VDGINT. 
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SS.Montr 
(Function code $92). Sets the monitor type 
Entry Conditions: 


A = path number 
B = $92 
X = monitor type 


0 = color composite 
1 = analog RGB 
2 = monochrome composite 
Error Output: 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


e SS.Montr loads the hardware palette registers with the 
codes for the default color set for three types of monitors. 
The system default initializes the palette for a composite 
color monitor. 


@ The monochrome mode removes color information from the 
signals sent to a monitor. 


@ When a composite monitor is in use, a conversion table 
maps colors from RGB color numbers. In RGB and mono- 
chrome modes, the system uses the RGB color numbers 
directly. 


@ The support modules for this call are VDGINT and GrfDrv. 
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SS.GIP 


(Function code $94). Sets the system wide mouse and key 
repeat parameters 


Entry Conditions: 


A = path number 
B = $94 
X = mouse resolution; in the most significant byte 


0 = low resolution mouse 
1 = optional high resolution adapter 
= mouse port location; in the least significant byte 
1 = right port 
2 = left port 
Y = = key repeat start constant; in the most significant byte 
= key repeat delay; in the least significant byte 
OOXX = no repeat 
FFFF = unchanged 


Error Output: 


CC 
B 


Additional Information: 


carry set if error 
error code, if any 


@ Because this function affects system-wide settings, it is 
best to use it from system configuration utilities and not 
from general application program. 


@ The support module for this call is CC3IO. 
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SS.UMBAR 


(Function code $95). Requests the high level menu manager to 
update the menu bar. 


Entry Conditions: 


A = path number 
B = $95 
Exit Conditions: 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


e An application can call SS.UMBar when it needs to redraw 
menu bar information, such as when it enables or disables 
menus, or when it completes a window pull down and needs 
to restore the menu. 


@ The support module for this call is WindInt. 
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SS.DFPal 
(Function code $97). Sets the default palette register values 
Entry Conditions: 


A = path number 
B = $97 
X = pointer to 16 bytes of palette data 


Exit Conditions: 


X = unchanged, bytes moved to system defaults 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


@® Use SS.DFPal to alter the system-wide palette register 
defaults. The system uses these defaults when it allocates a 
new screen using the DWSet command. 


@ Because this function affects system wide settings, it is 
best to use it from system configuration utilities, not gen- 
eral application programs. 
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SS.Tone 


(Function code $98). Creates a sound through the terminal 
output device. 


Entry Conditions: 


A = path number 
B =6$98 
X = duration and amplitude of the tone 


LSB = duration in ticks (60-sec) in the range 0-255 
MSB = amplitude of tone in the range 0-63 
Y = relative frequency counter (0=low, 4095 = high) 


Exit Conditions: 


These are the same as the entry conditions. There are no 
error conditions. 


Additional Information: 


@ This call produces a programmed IO tone through the 
speaker of the monitor used by the terminal device. You can 
make the call on any valid path open to term or to a win- 
dow device. 


@ The system does not mask interrupts during the time the 
tone is being produced. 


@ The frequency of the tone is a relative number ranging 
from 0 for a low frequency to 4095 for a high frequency. 
The widest variation of tones occurs at the high range of 
the scale. 
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Executable Memory Module Format 


Relative Check 
Address Use Range 
$00 
Sync Bytes ($87,$CD) 
$01 
$02 
Module Size (bytes) 
$03 
$04 
Module Name Offset header 
$05 parity 
$07 Attributes Revision 
module 
$08 Header Parity Check CRC 
$09 
Execution Offset 
$0A 
$0B 
Permanent Storage Size 
$0C 
$0D (Additional optional header 


extensions located here) 


Module Body 
object code, constants, 
and so on 


CRC Check Value 
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Device Descriptor Format 


Relative Check 
Address Use Range 
$00 

Sync Bytes ($87,$CD) 
$01 
$02 

Module Size (bytes) 

$03 
$04 

Offset to Module Name header 
$05 parity 
ee 
01 

Module 

$08 Header Parity Check CRC 
$09 

Offset to File Manager 
$0A Name String 
$0B 

Offset to Device Driver 

Name String 
sn 
$0E 
Device Controller 
SOF Absolute Physical Addr. 
(24 bit) 
$10 
$11 Initialization Table Size 
$12,.$12+n (Initialization Table) 
(Name Strings, and so on) 
CRC Check Value 
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INIT Module Format 


Relative Check 
Address Use Range 
00 
: Sync Bytes ($87,$CD) 
$01 
$02 
Module Size (bytes) 
$03 
$04 
Module Name Offset Resdar 
$05 parity 
$06 $F (Type) $1 (Lang) 
$07 Attributes Revision 
Module 
$08 Header Parity Check CRC 
$09 sit 
Forced Limit of Top 
$0A of Free RAM 
$0B 
$0C #IRQ Polling Table Entries 
$0D # Device Table Entries 
$0E 
Offset to Startup 
$0F Module Name String 
$10 
Offset to Default Mass 
$11 Storage Device Name String 
$12 
Offset to Bootstrap 
$13 Module Name String 
$14-n Name Strings 


CRC Check Value 
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Standard Floppy Disk Format 


Color Computer 3 


Physical Track Format Pattern 


Bytes 
Format (Dec) 


Header pattern 32 
(once per track) 12 


32 


Sector pattern 
(repeated 18 times) 


_— 
Co bo 


we) 
| We) On mm HO 
'Z, H DO OF CO DO DD FR ee 


Trailer pattern 
(once per track) 


Value 
(Hex) 


4K 
00 
F5 
FC 
4K 


00 

F5 

track number (0-34) 
side number (0-1) 
sector number (1-18) 
sector length code (1) 
CRC 

4E 

00 

F5 

FB 

data area 

CRC 

4E 


4E (fill to index mark) 
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System Error Codes 


The error codes are shown in both hexadecimal and decimal. The 
error codes listed include OS-9 system error codes, BASIC error 
codes, and standard windowing system error codes. 


Code Code Meaning 
HEX DEC 


$01 001 UNCONDITIONAL ABORT — An error occurred 
from which OS-9 cannot recover. All processes 
are terminated. 


$02 002 KEYBOARD ABORT — You pressed to 
terminate the current operation. 


$03 003 KEYBOARD INTERRUPT — You pressed 
[SHIFT |(BREAK] either to cause the current operation 
to function as a background task with no video 
display or to cause the current task to terminate. 


$B7 =: 1188 ILLEGAL WINDOW TYPE — You tried to 
define a text type window for graphics or used 
illegal parameters. 


$B8 184 WINDOW ALREADY DEFINED — You tried to 
create a window that is already established. 


$B9 185 FONT NOT FOUND — You tried to use a win- 
dow font that does not exist. 


$BA 186 STACK OVERFLOW — Your process (or pro- 
cesses) requires more stack space than is avail- 
able on the system. 


$BB = 187 ILLEGAL ARGUMENT — You have used an 
argument with a command that is inappropriate. 


$BD 189 ILLEGAL COORDINATES — You have given 
coordinates to a graphics command which are 
outside the screen boundaries. 


$BE 190 INTERNAL INTEGRITY CHECK — System 
modules or data are changed and no longer 
reliable. 


$BF 191 BUFFER SIZE IS TOO SMALL — The data you 
assigned to a buffer is larger than the buffer. 
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Code 
HEX DEC 
$CO 192 
$Cl1 193 
$C2 194 
SC3 195 
$C4 196 
$C8 200 
$C9 201 
$CA 202 
$CB 203 
$CC 204 
SCD. 206 
$CE 206 
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Code Meaning 


ILLEGAL COMMAND — You have issued a 
command in a form unacceptable to OS-9. 


SCREEN OR WINDOW TABLE IS FULL — You 
do not have enough room in the system window 
table to keep track of any more windows or 
screens. 


BAD/UNDEFINED BUFFER NUMBER — You 
have specified an illegal or undefined buffer 
number. 


ILLEGAL WINDOW DEFINITION — You have 
tried to give a window illegal parameters. 


WINDOW UNDEFINED — You have tried to 
access a window that you have not yet defined. 


PATH TABLE FULL — OS-9 cannot open the 
file, because the system path table is full. 


ILLEGAL PATH NUMBER — The path number 
is too large, or you specified a non-existent path. 


INTERRUPT POLLING TABLE FULL — Your 
system cannot handle an interrupt request, 
because the polling table does not have room for 
more entries. 


ILLEGAL MODE — The specified device cannot 
perform the indicated input or output function. 


DEVICE TABLE FULL — The device table does 
not have enough room for another device. 


ILLEGAL MODULE HEADER — OS-9 cannot 
load the specified module because its sync code, 
header parity, or Cyclic Redundancy Code is 
incorrect. 


MODULE DIRECTORY FULL — The module 
directory does not have enough room for another 
module entry. 


Code 
HEX DEC 
SCF 207 
$DO0 208 
$D1 209 
$D2 210 
$D3 211 
$D4 212 
$D5 213 
$D6 214 
$D7 = 215 
$D8 216 
$D9 217 
$DA 218 
$DB 219 
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Code Meaning 


MEMORY FULL — Process address space is full 
or your computer does not have sufficient memory 
to perform the specified task. 


ILLEGAL SERVICE REQUEST — The current 
program has issued a system call containing an 
illegal code number. 


MODULE BUSY — Another process is already 
using a non-shareable module. 


BOUNDARY ERROR — OS-9 has received a 
memory allocation or deallocation request that is 
not on a page boundary. 


END OF FILE — A read operation has encoun- 
tered an end-of-file character and has 
terminated. 


RETURNING NON-ALLOCATED MEMORY — 
The current operation has attempted to deallo- 
cate memory not previously assigned. 


NON-EXISTING SEGMENT — The file struc- 
ture of the specified device is damaged. 


NO PERMISSION — The attributes of the speci- 
fied file or device do not permit the requested 
Access. 


BAD PATH NAME — The specified pathlist con- 
tains a syntax error, for instance an illegal 
character. 


PATH NAME NOT FOUND — The system can- 
not find the specified pathlist. 


SEGMENT LIST FULL — The specified file is 
too fragmented for further expansion. 


FILE ALREADY EXISTS — The specified file- 
name already exists in the specified directory. 


ILLEGAL BLOCK ADDRESS — The file struc- 
ture of the specified device is damaged. 
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Code 
HEX DEC 
$DC 220 
$DD 221 
$DF 223 
$EO 224 
$E2 226 
$E3 227] 
$E4 228 
$E5 229 
$E6 230 
$E7 8231 
$E8 232 
$E9 2338 
$EA 234 


C-4 


Code Meaning 


PHONE HANGUP-DATA CARRIER DETECT 
LOST — The data carrier detect is lost on the 
RS-232 port. 


MODULE NOT FOUND — The system received 
a request to link a module that is not in the 
specified directory. 


SUICIDE ATTEMPT — The current operation 
has attempted to return to the memory location 
of the stack. 


ILLEGAL PROCESS NUMBER — The specified 
process does not exist. 


NO CHILDREN — The system has issued a wait 
service request but the current process has no 
dependent process to execute. 


ILLEGAL SWI CODE — The system received a 
software interrupt code that is less than 1 or 
greater than 3. 


PROCESS ABORTED — The system received a 
signal Code 2 to terminate the current process. 


PROCESS TABLE FULL — A fork request can- 
not execute because the process table has no 
room for more entries. 


ILLEGAL PARAMETER AREA — A fork call 
has passed incorrect high and low bounds. 


KNOWN MODULE — The specified module is 
for internal use only. 


INCORRECT MODULE CRC — The CRC for the 
module being accessed is bad. 


SIGNAL ERROR — The receiving process has a 
previous, unprocessed signal pending. 


NON-EXISTENT MODULE — The system can- 
not locate the specified module. 


Cc, 


Code 
HEX DEC 
$EB 235 
$EC 236 
$ED 237 
SEE 238 
SEF 239 
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Code Meaning 


BAD NAME — The specified device, file, or mod- 
ule name is illegal. 


BAD MODULE HEADER — The specified mod- 
ule header parity is incorrect. 


RAM FULL — No free system random access 
memory is available: the system address space is 
full, or there is no physical memory available 
when requested by the operating system in the 
system state. 


UNKNOWN PROCESS ID — The specified pro- 
cess ID number is incorrect. 


NO TASK NUMBER AVAILABLE — All avail- 
able task numbers are in use. 


Device Driver Errors 


I/O device drivers generate the following error codes. In most 
cases, the codes are hardware-dependent. Consult your device 
manual for more details. 


Code 
HEX DEC 
$FO 240 
$F1 241 
$F2 242 
$F3 243 
$F4 244 


Code Meaning 


UNIT ERROR — The specified device unit 
doesn’t exist. 


SECTOR ERROR — The specified sector number 
is out of range. 


WRITE PROTECT — The specified device is 
write-protected. 


CRC ERROR — A Cyclic Redundancy Code error 
occurred on a read or write verify. 


READ ERROR — A data transfer error occurred 
during a disk read operation, or there is a SCF 
(terminal) input buffer overrun. | 
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Code 
HEX DEC 
$F5 2465 
$F6 246 
$F7 247 
$F8 248 
$F9 249 
SFA 250 
$FB 251 
$FC 252 
$FD 253 
$FE 254 


C-6 


Code Meaning 


WRITE ERROR — An error occurred during a 
write operation. 


NOT READY — The device specified has a not 
ready status. 


SEEK ERROR — The system attempted a seek 
operation on a non-existent sector. 


MEDIA FULL — The specified media has insuf- 
ficient free space for the operation. 


WRONG TYPE — An attempt is made to read 
incompatible media (for instance an attempt to 
read double-side disk on single-side drive). 


DEVICE BUSY — A non-shareable device is in 
use. 


DISK ID CHANGE — You changed diskettes 
when one or more files are open. 


RECORD IS LOCKED-OUT — Another process 
is accessing the requested record. 


NON-SHAREABLE FILE BUSY — Another pro- 
cess is accessing the requested file. 


T/O DEADLOCK ERROR — Two processes have 
attempted to gain control of the same disk area 
at the same time. 


Index 


ACIAPAK 8-135 

active process 2-12 - 2-13 
queue 2-14, 8-98 
state 2-13 - 2-14 


address 
find 64K block 8-85 
lines 2-7 


polling 2-17 
space, add module 8-104 
age, process 2-14 
alarm, set 8-66 
allocate 
high RAM 8-69 
image 8-70 
memory 8-76 
memory blocks 8-67 - 
8-68 
process descriptor 8-71 
process task number 
8-73 
RAM 8-72 
allocation 
bit map 8-7 
map sector 5-1 
of memory 2-5 - 2-7 
polling 2-17 
allocation map 


clear 8-13 

disk 5-3 
alpha screen 

cursor 8-118 

memory 8-117 
ASM assembler 8-2 
assembler, RMA 8-2 
attach a device 8-44 - 8-45 
attribute 

byte 5-5, 

file 5-12 


background color, get 8-129 
bell, set alarm 8-66 
bit map 2-5 

allocation 8-7 


bit map (cont’d.) 
search memory 
allocation 8-33 
block 
allocate system 
memory 8-105 
deallocate system 
memory 8-106 
map into process 
space 8-96 
number 2-7 
scroll 8-139 
block map, system 8-18 
boot 
file, load 5-26 
module, link 8-75 
booting OS-9 1-3 
bootstrap 
memory request 8-76 
system 8-75 
border color, get 8-129 
buffer 
map (Get/Put) 8-138 
reserve graphics 8-136 
button 
state, mouse 8-124 - 
8-125, 8-126 
timeout, mouse 8-140 
byte 
attribute 5-5 
deallocate 64-byte 
block 8-101 
get from memory 
block 8-94 
get two bytes 8-95 
read from path 8-59 - 
8-60 
store in task 8-109 


calling process 
insert in I/O queue 8-91 
terminate 8-14 
turn off 8-35, 8-43 
CC3DISK 1-2 
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CC3GO module 2-19 


CC3IO_ 1-2, 6-1 
chain 8-8 - 8-9 
change 


device operating 
parameters 5-23 
directory 8-46 
character 
read SCF input 6-13 
write, SCF 6-14 
ChgDir 4-4 
child process 2-13 
create 8-15 - 8-17 
clear specified block 8-77 
click 8-126 
CLOCK 1-2 
clock 
module 1-2, 2-19 
real-time 2-12, 2-17 
close 
file 4-7 
path 8-47, 8-135 
codes 
signal 2-15 
system error C-1l 
command interpreter 1-4 
communication, 
interprocess 2-15 
compact module directory 
8-88 
compare strings 8-10 
compatibility with Level 
One 2-1 
concurrent execution 7-1 - 7-3 
copy external memory 8-11 
count, link 2-5 
counter start, mouse 8-124 
CPU 2-7 
time 4-11 
CRC 
calculate 8-12 
validate module 8-111 
value 3-1 - 3-3 
create 
directory 8-55 - 8-56 


create (cont’d.) 
file 8-48 - 8-49 
current 
data directory 8-51 
execution directory 8-51 
cursor positioning 4-5 
cyclic redundancy check 3-1 - 


DAT 
hardware 8-99 
registers 8-103 
to logical address 8-78 
data 
available, SCF test 
8-113 
directory 8-51 
stream 4-3 
transfer, pipes 7-1 - 7-3 
move in memory 8-97 
DAT image 8-70 
conversion 8-78 
copy into process 
descriptor 8-102 
deallocate block 8-77 
high block 8-86 
low block 8-87 
pointer 8-95 
DAT task number 
release 8-99 
reserve 8-100 
date 
get system 8-40 
set 8-38 
deadlock 5-13 
deadly embrace 5-13 
deallocate 
image RAM blocks 8-79 
map bits 8-13 
process descriptor 8-80 
RAM blocks 8-81 
task number 8-82 
default palette registers 
8-129, 8-149 
delete file 8-50 - 8-51 


descriptions, system call 8-2 
descriptor 
get process 8-20 
path 4-18 
pointer 8-82 
process 2-13 
detach device 8-52 
device 
add or remove from 
polling table 8-92 
attach 8-44 - 8-45 
attachment, verify 


8-44 


controller 5-15 

control registers, 
initialize 6-12 

control registers, SCF 
6-12 

descriptor 1-4, 4-2, 4-17, 
A-2 

detach 8-52 

modules 5-15 

modules, RBF 5-8 - 5-10 

modules, SCF 6-6 - 6-8 

name, get 8-115 

open path to 8-57 - 8-58 

operating parameters, 
RBF 5-23 

operating parameters, 
SCF 6-15 

status 2-17 - 2-18, 8-63 

status, get 8-54 

table 4-2, 8-52 

terminate, RBF 5-24 

terminate, SCF 6-16 

write to 8-64 - 8-65 

device driver 1-3, 4-11 

close path 8-135 

modules 4-8 

name 5-15 


SCF 6-9 - 6-17 

SCF subroutines 6-10 - 
6-17 

subroutines, RBF 5-16 - 
5-27 


Index 


device driver modules, 
RBF 5-13 - 5-17 
device interrupt 5-25 
SCF 6-17 
directory 
attribute byte 5-5 
change 8-46 
disk 5-5 
entry, module 8-83 
get module 8-19 
make 8-55 - 8-56 
module 2-12, 8-88 
disk 
directories 5-5 
sector read 5-19, 5-21 
disk allocation map 5-3 
sector 5-1 
diskette format B-1 
display 
screen 8-143 
status, get 8-115 
drag 8-126 
drive head, restore 8-131 
duplicate path 8-53 


editing, line 6-1, 8-61 
end-of-file, test for 8-114 
equate file 2-4 
equivalent logical address 
8-78 
error 
- codes, system C-1 - C-6 
message, write 8-30 
print 8-30 
exclamation point, pipes 7-1 - 
7-3 
execute 
mode 5-11 
system calls 8-1 - 8-2 
execution 
directory 8-51 
offset, module 3-7 
exit calling process 8-14 
external memory, read 8-11 
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fatal signal 2-13 

file 
attribute byte 5-12 
closing 4-7 
create 4-4, 5-12, 8-48 - 

8-49 
deadlock 5-13 
delete 4-5, 8-50 - 8-51 
descriptor 5-3 - 5-4 
execute mode 5-11 
get pointer position 
-114 

line reading/writing 4-6 
load module 8-29 
locking 5-12 
non-shareable 
opening 4-4 
open path 8-57 - 8-58 
permission bits 5-4 
pipe 7-1 - 7-3 
pointer 4-5, 8-62 
position, RBF 8-114 
read 5-1, 4-5 
sharing 5-12 
size, get 8-114 
status, get 8-54, 8-114 
update mode 5-11 
write line to 8-64 - 8-65 
writing 4-6 

file manager 1-3 
modules 4-3 
name 5-15 

find 


5-12 


64-byte block 8-85 
module directory 
entry 8-84 

fire button 8-123 - 8-127 
FIRQ 4-12 

interrupt 2-17 
flag, RAM In Use 8-81 
flip byte 2-17 
floppy diskette format B-1 
foreground color, get 8-129 
FORK 2-8 
fork, child process 8-15 - 8-17 


FORMAT 5-2 
format 
device descriptor 4-17, 
A-2 
INIT module A-3 
memory module 3-6 - 
3-7, A-1 
of device driver 
modules 4-10 
track 8-132 
function 
calls 2-4 - 2-5, 8-1 
key sense 8-133 


get 
abyte 8-94 
free high block 8-86 
free low block 8-87 
ID 8-22 
process pointer 8-89 
status 8-54 
Status system calls 
8-112 - 8-130 
system time 8-40 
Get/Put buffer, map 8-138 
GETSTA 8-112 
SCF 6-15 
GetStat 4-6 
Getstats 5-23 
graphics buffer 
reserve 8-136 
select 8-137 
graphics interface 1-2 
GRFINT 1-2 


handler routine, virtual 
interrupt 8-110 

hard disk shutdown 8-133 

hardware 
controller, SCF 6-9 
DAT registers 8-103 
vector 2-16 

header 
module 3-1 - 3-2 
parity 8-111 


Index 


header (cont’d.) 
pattern, floppy 
diskette B-1 
high block, memory search 
8-86 
high-level 
menu handler 8-122 
menu manager 8-148 
window handler 8-139 
high-resolution 
mouse adapter 8-126 
screen, allocate 8-142 
hold, button 8-126 
1/O 
calls 2-4 - 2-5, 8-1 
device accessing 2-11 
module, delete 8-90 
path, close 8-47 
queue, insert calling 
process 8-91 
I/O system 1-3 - 1-4 
calls 2-1, 8-2 
system modules 
1-4, 4-1 
transfers 4-8 


1-1 - 


ID 
return caller’s 
process 8-22 
set user 8-39 
identification sector 5-1 
image, allocate 8-70 
INIT 1-2, 5-18 
INIT module 2-17 
format A-3 
link 8-75 
Init, SFC 6-12 
initialization table, SCF 
device 6-6 - 6-8 
initialize device memory 5-18 
input buffer, read SCF 
character 6-13 
insert process 8-74 
install virtual interrupt 
8-110 
intercept, set signal 8-21 


interface 
graphics 
VDG 4-2 
Windint 4-2 
interprocess 
communication 2-15 
interrupt 
device 5-25 
enable, SCF 6-12 
FIRQ 2-17 
processing 2-1 
IOMAN 1-2 
IRQ 4-12 
add/remove device from 
polling table 8-92 
interrupt 2-17 
polling 2-17 
polling table 2-18 
service routine 5-25 
IRQSVC routine 4-13 
IRQSV 4-11 


1-2 


joystick value, get 8-116 


kernel 1-2 
key 
repeat parameters, 
set 8-147 
sense function 8-133 
status, get 8-120 
keyboard scan 2-17 


language byte 3-4 
line 
editing 6-1, 8-61 
reads 4-6, 8-61 
writes 4-6, 8-65 
link 
to memory module 8-23 
- 8-24, 8-28 
using module directory 
entry 8-83 
link count 2-5 
decrease 8-42 
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load 
boot file 5-26 
byte from memory 
block 8-94 
from task offset 8-93 
module 8-25 - 8-26, 8-29 
two bytes 8-95 
lock, end-of-lock 5-12 


locking 

files 5-12 

record 5-10 - 5-11 
logical 


address space 2-6, 2-8 
sector number 5-1 
LSN_ 5-2, 5-5 


macro 2-4 
MAKDIR 4-4 
make directory 8-55 - 8-56 
manager 
file 1-3 
random block 1-3 
sequential file 1-3 
map 
block 8-96 
search allocation 8-33 
mask byte 2-18 
memory 
allocate 8-76 
allocate blocks 8-67 - 
8-68 
allocate high RAM 8-69 
change process data 
size 8-27 
deallocate 2-5 
find low block 8-87 
free screen 8-144 
map 2-6 
module format 3-6 - 3-7, 
A-1 
module, link 8-23 - 8-24 
move data 8-97 
page 2-5 
pool 8-80 
request, bootstrap 8-76 


memory (cont’d.) 
segment 2-8 
memory allocation 2-5 - 2-7 
memory block 2-7 
find 64K 8-85 
get byte 8-94 
get high 8-86 
map 8-81 
map, search 8-72 
memory management 2-1, 2-5 
- 2-12 
unit 2-7 - 2-8 
menu 
manager, update 
request 8-148 
selection 8-122 
message, write error 8-30 
MMU registers 2-8 
mnemonic name, LSN 
MODPAK 8-135 
module 
add into address 
space 8-104 
body 3-1 - 3-2 
clock 2-19 
CRC calculate 8-12 
decrease link count 8-42 
delete I/O module 8-90 
device descriptor 5-15 
device driver 4-8 
file manager 4-3 
finding 2-12 
format 3-1 - 3-3 
link 8-28 
link count, decrease 
8-42 
linking 1-2 
load 8-25 - 8-26, 8-29 
load and execute 
primary 8-8 - 8-9 
name 3-3 
RBF-type device 
drivers 5-13 - 5-17 
SCF device descriptor 
6-6 - 6-8 


5-2 


Index 


module (cont’d.) 
types 3-1, 3-5 
unlink 8-41 
validate 8-111 
module directory 2-5, 2-12 
compact 8-88 
entry, link using 8-83 
find 8-84 
get 8-19 
pointer 8-84 
module header 3-1 - 3-3, 5-15 
SCF device driver 6-9 
monitor, set type 8-146 
mouse 
button state 8-125 
button timeout 8-140 
click 8-122 
coordinates 8-127 
countdown 8-125 
countup 8-125 
parameters, set 8-147 
port 8-125 
resolution 8-126 
screen position 8-126 
send signal to process 8- 
1 


status, get 8-123 
timeout 8-124 
window working area 
8-127 
move data 8-97 
multiplexer 2-8 
multiprogramming 2-12 - 
2-16 
management 2-1 
multitasking 1-2 


name parse 8-31 - 8-32 
names, compare 8-10 
next process 8-98 

NMI interrupt 2-17 
non-shareable file 5-12 
number, path 8-53 


open 
file 8-48 - 8-49 
path 8-57 - 8-58 
operation of memory 
management 2-8 - 2-12 
OS-9 
Level One 
compatibility 2-1 
modules 1-2 
scheduler 2-14 - 2-15 
OS9P3 2-1 
module 2-2 


packet size 8-124 
palette, get information 8-127 
palette register 8-129 
set default 8-149 
settings 8-129 
parameters, mouse and key 
repeat 8-147 
parent 
directory 5-3 
process 2-13 
parity 8-135 
parse name 8-31 - 8-32 
path 
close 8-47, 8-135 
duplicate 8-53 
open 8-57 - 8-58 
read bytes 8-59 - 8-60 
table 4-2 
path descriptor 4-18, 5-5 - 
5-8 


read option section 
8-112 
SCF 6-2 - 6-6 
write option section 
8-130 
permanent storage size, 
module 3-7 
physical address space 2-7 
pipe file manager 4-3 
PIPEMAN 1-2 - 1-3, 4-3 
pipes 4-3, 7-1 - 7-3 
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process descriptor 2-13 - 
2-14, 8-102 
deallocate 8-80 
descriptor, allocate 8-71 
get 8-20 
pointer 8-82 
processes 
active 2-12 
data size, change 8-27 
process ID 2-13 
return caller’s 8-22 
pseudo vector 2-16 
PutStat 4-6 


RAM 2-5 - 2-7 
allocate 8-69, 8-72 
allocate blocks 8-70 
allocation 2-13 
blocks, deallocate 8-81 
blocks, deallocate 
image 8-79 
interrupt vector 2-18 
random 
access 9-1 
block file manager 1-3, 
4-3 
RBF 
change file size 8-131 
format track 8-132 
get file size 8-114 
manager 4-3 
tables 5-14 - 5-17 
read 
bytes 8-59 - 8-60 
device operating 
parameters 5-23 
disk sector 5-19 
external memory 8-11 
input character, SCF 
6-13 
line 6-2, 8-61 
mode 5-11 
system call 6-1 
real-time clock 2-12, 2-17 
record locking 5-10 


reference 
System Mode calls 8-5 - 
8-6 
User Mode system 
calls 8-3 - 8-4 
registers 
DAT 8-103 
MMU 2-8 
release a task 8-99 
request system memory 
8-105 
reserved memory 2-5 - 2-7 
reserve task number 8-100 
return 
64 bytes 8-101 
system memory 8-106 
RMA assembler 8-2 
ROOT directory 5-3, 5-5 
RTS instruction 2-18 


SCF 
configure serial port 
8-134 - 8-135 
data available test 
8-113 
device control 
registers 6-12 
Getsta 6-15 
manager 4-3 
path descriptor 6-2 - 6-6 
terminate device 6-16 
scheduler, OS-9 2-14 - 2-15 
screen 
allocate high- 
resolution 8-142 
convert type 8-145 
display 8-143 
free memory 8-144 
mouse position 8-126 
palette 8-127 
size, get 8-119 
type 8-128, 8-142, 8-145 
scroll block, install 8-139 
search bits 8-33 


Index 


sector 5-3 
pattern, floppy 
diskette B-1 
seek, file pointer 8-62 
segment, memory 2-8 
select graphics buffer 8-137 
send signal 8-34 
sequential character 
file manager 1-3, 4-3 
VO 6-1 
serial port configuration 
8-121 
service 
request processing 2-1 
routine, IRQ 5-25 
set 
alarm 8-66 
date 8-38 
TRQ 8-92 
priority 8-36 
process DAT image 
8-102 
process task DAT 
registers 8-103 
status 8-63 
SVC 8-107 - 8-108 
SWI 8-37 
time 8-38 
user ID 8-39 
Setstats 5-23 
Set Status system calls 8-130 
- 8-150 
shareable bit 3-5 
sharing, file 5-12 
shell 1-4 
shutdown hard disk 8-133 
signal 2-15 - 2-16 
codes 2-15 
fatal 2-13 
from mouse to 
process 8-141 
intercept trap 2-15 - 
2-16 
intercept, set 8-21 
send to process 8-34 


single-user 

attribute 5-12 

bit, files 5-12 
size 

of screen 8-119 

of window 8-119 
sleep 

calling process 8-35 
sleeping process 2-14, 2-16 
slices, time 2-12 
sound, create 8-150 
speaker, create sound 8-150 
state 

active 2-13 

of button 8-126 

sleeping 2-14 

suspend 4-13 

waiting 2-13 
static storage address 2-18 
status 

display 8-115 

get, SCF 6-15 

get mouse 8-123 - 8-127 

of key 8-120 

register 2-17 

set, SCF 6-15 
status, get 8-54 
status, set 8-63 
store byte in atask 8-109 
string, scan input 8-31 - 8-32 
strings, compare 8-10 
subroutines 

RBF device driver 5-16 - 

5-27 
SCF device drivers 6-10 
- 6-17 

suspend 

bit 4-13 - 4-14 

state 4-13 
SWI, set 8-37 
SWI2 instruction 2-4 
symbolic names 2-4 
sync byte 3-3 
synonymous path number, 

return 8-53 
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system 
block map, get 8-18 
boot 1-3 


bootstrap 8-75 
date, get 8-40 
device, attach 8-44 
error codes C-1 - C-6 
initialization 2-1 
link 8-104 
mode call reference 8-5 - 
8-6 
time, get 8-40 
system call 
add 8-107 - 8-108 
descriptions 8-2, 2-4 
execution 8-1 - 8-2 
get status 8-112 - 8-130 
mnemonics names 8-1 
User Mode reference 8-3 
- 8-4 
system memory 
allocate high RAM 8-69 
block map 8-81 
deallocate 8-106 
module directory, get 
8-19 
request 8-105 
system modules 1-1 - 1-4 


table 
device 8-52 
IRQ polling 2-18 
RBF 5-14 - 5-17 
SCF device descriptor 
6-6 - 6-8 
VIRQ 2-20 
task 
' map 2-12 
offset, load from 8-93 
register 2-8 
release 8-99 
store byte 8-109 
task number 8-73 
DAT 8-100 
deallocate 8-82 
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terminal, create sound 8-150 
terminate 
a device 5-24 
calling process 8-14 
SCF device 6-16 
ticks 4-11 
time 
CPU 4-11 
get system 8-40 
set 8-38 
sharing 2-11 
slice 2-16, 2-12 
timeout, mouse 8-124 
track 
format 8-132 
restore drive head 8-131 
trailer pattern, floppy 
diskette B-1 
trap, signal intercept 2-15 - 
2-16 
type 
convert screen 8-145 
of screen 8-128 
set monitor 8-146 
window screen 8-142 


unlink module 8-41 - 8-42 
update mode 5-11 
user calls 2-5 
user ID 2-13 
set 8-39 
User Mode system calls 
reference 8-3 - 8-4 


validate module 8-111 
VDG 1-2 
alpha screen cursor 
8-118 
alpha screen memory 
8-117 
interface 4-2 
vector 
pseudo 2-16 
set SWI 8-37 
vectoring 2-16 


verify device attachment 
8-44 - 8-45 
video display generator 1-2 
VIRQ 2-19 - 2-20 
polling table 2-19 - 2-20 
virtual interrupt, install 
8-110 


wait 
calling process 8-43 
state 2-13 - 2-14 
waiting process 2-13 
wildcard 4-6 


WINDINT 1-2 
Windint interface 4-2 
window 


descriptors 1-2 

high-level handler 8-139 

pointer location 8-124 

screen, type 8-142 

size, get 8-119 

type 8-145 

working area, mouse 
8-127 


Index 


working directory, change 
8-46 
write 
character to SCF 
output 6-14 
disk sector 5-21 
path descriptor 8-130 - 
8-131 
to file or device 8-64 
write line 8-65 
line system call 6-2 
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